This is a silly question, but it's on my mind.
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.
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.
** Attending API Strategy & Practice conference? **
Isn't this essentially the "code-on-demand" aspect of REST?
API is just "Application Programming Interface", i.e. an interface.
It doesn't have to be a networked API (Web APIs); it can also be a
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.
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.
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)
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?
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:
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.
On Oct 8, 2012, at 8:18 PM, Jack Repenning <repenni...@gmail.com> wrote: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.
Social Media Software Engineer -
San Francisco, CA
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.