Is JavaScript API the right term?

[landlessness]

Craftsfolk, 

This is a silly question, but it's on my mind.

Just built an app using HTML5 & JavaScript using the 'JavaScript APIs' from Google Maps and LinkedIn.

Along the way whenever I visited their dev sites (https://developers.google.com/maps/documentation/javascript/reference & https://developer.linkedin.com/documents/javascript-api-reference-0) I kept thinking, this isn't a JavaScript API.

It's a JavaScript library calling an API.

Am I whack? Anyone else think the JavaScript API naming is weird? Isn't it a JavaScript library (or sdk)? Does the naming matter? :~)

-b

[Kin Lane]

I don't think you are whack.  It's more of the conundrum that is the last Web APIs movement.   What is an API?  REST?  SOAP?  What makes the movement successful?  Everyone has their opinions.

I classify JavaScript API under, "Embeddable".  

If you build a button, badget, widget or sophisticated JS app.  It's client side and thus can be embedded anywhere.  It's build for syndication and embeddability. 

Google Maps was built for hackability.  I remember Lars talking about this in the early days, in one of his keynotes.  The JS isn't the API.  The API drives the JS.

Companies like Band Page, do the JS embed driven by API, but don't release the API.  It's there.  They acknowledge that savvy devs will hack it, and they won't prevent it.  Much like google maps team admitted to.

I think naming matters.  I think your right.  JS API is not right, but I don't think my approach is either.  

I find advocating for an API is first.  Whether you make that public or not is up to you.  Then a healthy embeddable strategy is important, either way.

I think JS is inherently client side or SDK...but then again NodeJS has bucked that trend.  

But great conversation and thoughts.  I think you have opened up something, few discuss.  

And needs more discussion.

Kin Lane

kin...@gmail.com

apievangelist.com / apivoice.com

** Attending API Strategy & Practice conference? **

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Mike Schinkel]

Kin,

Isn't this essentially the "code-on-demand" aspect of REST?

-Mike

[Jon Moore]

API is just "Application Programming Interface", i.e. an interface[1].
It doesn't have to be a networked API (Web APIs); it can also be a
library, which also has a programming interface. A "Javascript API" is
just something callable from Javascript.

Jon

[1] http://en.wikipedia.org/wiki/Application_programming_interface

........
Jon Moore

[Enrique Amodeo]

I'm with Jon here. For years we have been using non networked APIs. So the thing you use from Google it is a library that provides a JS API. That's it.

Other topic is if it is better to provide REST APIs or languages "embedded" APIs. I don't believe there is a single right answer to this questions, so perhaps it is better to provide both of them: a web api and a library api in some popular language.

Cheers,

Enrique

[sune jakobsson]

If there is a "language" preposition it means in most cases that the API has been tailored for that language, or comes accompanied with a library of that particular language.

Meaning "Javacript API", the API is "easy" to use from Javascript, either because of a library or direct use.

Sune

[Enrique Amodeo]

This thread remembers me of a discussion I have with a friend about this. What are the advantages/disadvantages of using a web API vs. language APIs? 

The good points of a language API: as a service consumer, if there is an API for your language, it is far easier to consume the services than with a web API (if it is well designed of course)

Bad points:

a) As a service provider you typically need to implement several libraries (JS, Java, Ruby, Python), maintain them all and distribute them.

b) There is the risk you don't focus on the HTTP/REST details, so you end with an implementation that doesn't play well with the web. Pretty easy to get an RPC design in your library that doesn't translate very well to REST.

c) If you don't provide a web API, or document it, the language API is effectively the only way to access your services, and your consumers are immersed in a vendor lock in scenario.

If you go for an only web APIs approach, you solve most of the problems of a language API. But in my experience only a few developers understand REST and HTTP in an effective way, so your potential base of consumers is lower. Of course there are frameworks, but if a framework does not support well the concept of hypermedia, it won't be very effective consuming hypermedia apis. That's one reason why we don't see a lot of hypermedias APIs nowadays. The point of having an API is making easy for people to consume your services, and a lot of guys think this hypermedia/REST approach is too confusing.

Perhaps code on demand could be a good compromise?

Cheers,

Enrique

[Jack Repenning]

On Oct 5, 2012, at 2:44 AM, Enrique Amodeo <eamode...@gmail.com> wrote:

The good points of a language API: as a service consumer, if there is an API for your language, it is far easier to consume the services than with a web API (if it is well designed of course)

I would challenge that "far easier" idea, particularly with a well-designed REST API. For example, I write a lot of Ruby test scripts that call my API like this:

  response = RestClient.post url, { :credentials => credentials,

    :shortName => "artf#{ artf }proj_2_#{ dither }",

    :longName => "Artf#{ artf } Project 2 #{ dither }"

  }, :content_type => 'application/json', :cookie => session_cookie

  json_response = JSON.parse(response)

That's very similar to how a Ruby language API call would look. In fact, pretty much the only differences are the :content_type and :cookie parameters (probably handled from within a language API), and the JSON.parse() call to transform the response back into a Ruby hash (which is probably what a language API would return).

Most app-dev languages today have something rather like Ruby's RestClient, I think, making the gap between language and REST APIs pretty narrow.

<><
Jack Repenning

[Mike Schinkel]

On Oct 8, 2012, at 8:18 PM, Jack Repenning <repenni...@gmail.com> wrote:
> I would challenge that "far easier" idea, particularly with a well-designed REST API. For example, I write a lot of Ruby test scripts that call my API like this:

In my experience calling GETs is generally easy, POSTs a bit harder, but the real annoyance is authentication and robust maintenance of said authentication (oAuth's refresh_token, for example.) A good client SDK makes that a lot easier.

-Mike

[justin kruger]

I would think you could say, JavaScript could be an API or SDK, but REST APIs are not SDKs.

I might reserve the notion of SDK for something that includes a compiler or something that provides a set of tools beyond the JavaScript code.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.

--
--
--
Justin Kruger
Social Media Software Engineer -
San Francisco, CA

--
http://twitter.com/jdavid
http://www.linkedin.com/in/jdavid

[Enrique Amodeo]

Jack, the code you show is ok for most of the people on this mail group, but I don't think is ok for the average developer. Furthermore its level of abstraction is only slightly above a plain http client. From the point of view of an application logic consumer I'd like to see application concepts in the API not HTTP concepts like cookies, methods and mime types. This HTTP concepts should be in a lower layer.

The problem is that the average developer is confused by things like when to use put and post, how to handle versions and cache, security, how to do hypermedia controls, etc.

In a language API this concepts should be solved and the corresponding design decisions implemented. That's why it is easier. Of course this approach have some other problems as I wrote in this same thread. But I suspect it will be the more widespread approach in the near future.

Cheers,

Enrique Amodeo 

[Enrique Amodeo]

Agree!