Clear deprecation policies are great, but I also think that every public API needs to be explicitly versioned. This is commonly achieved by including the version in the URL (api.example.com/v3/whatever), but a suitable header (API-Version: 20120420) would also work.
Once published, a specific version of an API should never change in a backward-incompatible way, only become superseded by newer versions. Likewise, you don't change or deprecate individual methods, you merely stop supporting older versions. That would make it much easier for developers to keep track of API changes.
That definitely seems like the common-sense approach. There was an interesting article posted on here recently though, which argued that API versioning is an anti-pattern.
It makes some good points, although I'm not sure I entirely agree with the conclusion drawn, since it places all of the responsibility on the authors of the client-side code:
That looks like a too rigid view of what REST requires.
It's possible to view different versions of an API as different representations of the same data. For example, an HTTP server is permitted to return different responses, or even return an error, depending on the contents of the client's "Accept:" header. If versioning was done with a header instead of the URL, it would achieve essentially the same results. The client would be saying "I want /user/123/posts/recent, and I want it in the APIv3 format."
If an API method changes so much that it is no longer recognizable as a different representation of the same data, the URL should probably change to reflect the new content. The old URL would then return data only when the old version is requested, and "406 Not Acceptable" when the new version is requested. So I don't see any reason why API versioning can't be RESTful. It's just slightly more difficult to do it RESTfully, compared to adding the version in the URL.
In any case, I'd rather take practicality over RESTful purity.
This is one of the best arguments for scraping data, if you can manage it. Generally businesses invest much more time and resources into maintaining an up-to-date, usable website than they would on an API, especially if they don't use a service-oriented architecture internally (ie, consume their own API)
How often do websites really change the layout of their DOM? Sure, some sites that are actively developed (ie social networks) but for a lot of business websites where information doesn't change that often, like restaurants, reviews or clothing, websites are pretty consistent.
Plus, building a parser isn't always that much more work than trying to build a client for a convoluted API.
It's obviously case-by-case, but I think a lot of people dismiss scraping outright when there are a lot of useful applications.
Scraping data for offline processing, but certainly should not be for user-facing traffic. Cosmetic tweaks can blow up the scraper's parser, UI technologies are built on a taller stack and are prone to higher latencies and points of failure, yada yada.
as I have tried to start a business building on top of API's, this is in general a risky business. Not only can they disappear, but also work incorrectly, go down, change overnight without notification. Also your access can be shut down just because of a change of heart on their side
If you don't pay for access and have some kind of contract (Twitter firehose, Bing API), yes your business goals are not aligned and you'd better prepare for the worse.
Did you design your software or business plan with an API contingency plan? Some web APIs have reasonable replacements, but most offer some unique value.
Programmable Web noticed this last year when Google started charging more for their older APIs. Why kill the API when you can make as much money as you want from its users?
> Google is also providing developers a reason to finally move their maps off of Google Maps V2. Overages for the old version of Google Maps costs $10 per 1,000 map views.
This makes me think of the not-so-recent deprecation of Offline Access by Facebook.
I do not know whether it will be supported ad infinitum, but if not, it requires other completely-functional apps to be majorly rearchitected or break entirely.
There is rarely a good reason to actively destroy old API - section it off, keep it out of new code, maybe even kill the documentation so new developers don't use it, but it's bad business and downright disrespectful to the third-party developers who enrich your platform.
How does one build a software that will not deteriorate over time, if he uses unstable API?. I don't know. Just don't use unstable API if you don't have to.
17 comments
[ 4.0 ms ] story [ 47.8 ms ] threadOnce published, a specific version of an API should never change in a backward-incompatible way, only become superseded by newer versions. Likewise, you don't change or deprecate individual methods, you merely stop supporting older versions. That would make it much easier for developers to keep track of API changes.
It makes some good points, although I'm not sure I entirely agree with the conclusion drawn, since it places all of the responsibility on the authors of the client-side code:
https://secure.designinghypermediaapis.com/nodes/bujxbmhffep...
"This can be handled in the opposite way we dealt with new functionality: if you don't see something, don't display it."
In my experience that is just too simplistic idea to cover all cases hence the need for versioning.
It's possible to view different versions of an API as different representations of the same data. For example, an HTTP server is permitted to return different responses, or even return an error, depending on the contents of the client's "Accept:" header. If versioning was done with a header instead of the URL, it would achieve essentially the same results. The client would be saying "I want /user/123/posts/recent, and I want it in the APIv3 format."
If an API method changes so much that it is no longer recognizable as a different representation of the same data, the URL should probably change to reflect the new content. The old URL would then return data only when the old version is requested, and "406 Not Acceptable" when the new version is requested. So I don't see any reason why API versioning can't be RESTful. It's just slightly more difficult to do it RESTfully, compared to adding the version in the URL.
In any case, I'd rather take practicality over RESTful purity.
2. Who says it goes down? Might just have stale or incorrect data before the tweak is patched.
Plus, building a parser isn't always that much more work than trying to build a client for a convoluted API.
It's obviously case-by-case, but I think a lot of people dismiss scraping outright when there are a lot of useful applications.
Scraping data for offline processing, but certainly should not be for user-facing traffic. Cosmetic tweaks can blow up the scraper's parser, UI technologies are built on a taller stack and are prone to higher latencies and points of failure, yada yada.
The Yelp API doesn't expose a given user's public bookmarks, reviews, etc., but they can be easily scraped from the user-facing website.
http://www.yelp.com/developers/documentation/v2/overview
If you don't pay for access and have some kind of contract (Twitter firehose, Bing API), yes your business goals are not aligned and you'd better prepare for the worse.
> Google is also providing developers a reason to finally move their maps off of Google Maps V2. Overages for the old version of Google Maps costs $10 per 1,000 map views.
http://blog.programmableweb.com/2011/10/27/google-maps-usage...
There is rarely a good reason to actively destroy old API - section it off, keep it out of new code, maybe even kill the documentation so new developers don't use it, but it's bad business and downright disrespectful to the third-party developers who enrich your platform.