Ask HN: Who makes the best APIs?
24 comments
Just keep it simple..that's the most important thing. Simple POST name/value pairs and JSON output. I don't care if it's technically REST or not. One big long document describing every call and response (makes it easy to search with CTRL-F). Lots of examples. Complete example code. High level libraries that implement the boring parts. A direct email address to the developer.
Twilio's REST API (http://www.twilio.com/docs/api_reference/REST/) is really easy to understand, very sensible. It's practically self-documenting, but it's backed up with thorough documentation and examples. One can get up and running very quickly because of that. They have clearly spent a lot of time getting the API right.
Paypal has one of the worst APIs I've ever used. It's a useful model of what to avoid, particularly its multiple formats and its flakey and often outdated sandbox testing servers.
The Last.fm API (http://www.last.fm/api/intro) is the best one I've come across.
It has the most comprehensive and intuitive documentation of all the APIs I've used. Their format for API documentation should become a standard.
It has the most comprehensive and intuitive documentation of all the APIs I've used. Their format for API documentation should become a standard.
Take a look at Friendfeed's API V2 (http://friendfeed.com/api/documentation). Not only does it use very intuitive RESTful architecture, but it also has very awesome documentation and libraries.
Of course, now that they're with Facebook the developer support will likely not be as good, but the API is great as it is regardless.
Of course, now that they're with Facebook the developer support will likely not be as good, but the API is great as it is regardless.
It's not a web service, but I always thought Qt had one of the best APIs out there in terms of style, consistency, and documentation. It's worth looking at just from a packaging perspective.
I like 37signals Basecamp API (not as much Highrise and Campfire), but a standout for me is Wufoo's:
http://wufoo.com/docs/api/
Really nicely documented.
http://wufoo.com/docs/api/
Really nicely documented.
Amazon has the most useful APIs out there. Don't copy them though.
So many small companies put out giant behemoth APIs with crazy security hoops because that's what Amazon does and Amazon's stuff is really cool. As a result, nobody outside the dev team can figure out how to authenticate, so nobody actually uses the API.
Check out Twiddla's API (http://www.twiddla.com/API/) for an example of how to keep things lightweight. 2 POST endpoints and an IFRAME syntax. Only the bare minimum security, and a huge emphasis on getting your thing up and running without having to sweat the API.
So many small companies put out giant behemoth APIs with crazy security hoops because that's what Amazon does and Amazon's stuff is really cool. As a result, nobody outside the dev team can figure out how to authenticate, so nobody actually uses the API.
Check out Twiddla's API (http://www.twiddla.com/API/) for an example of how to keep things lightweight. 2 POST endpoints and an IFRAME syntax. Only the bare minimum security, and a huge emphasis on getting your thing up and running without having to sweat the API.
Definitely read what Joshua Bloch has to say about API design. I'd highly recommend this talk he gave: http://www.infoq.com/presentations/effective-api-design
Typically he talks about APIs more in the sense of library design than web service design, but he's very relevant nontheless.
Typically he talks about APIs more in the sense of library design than web service design, but he's very relevant nontheless.
I suggest taking your time when you implement the first version of your API. Nothing is worst than developing based on a rushed v1 API, which later gets modified without you knowing. No one wants to be caught calling a deprecated function that then gets removed.
Furthermore, try to keep all of your API libraries up-to-date. For example, I was almost driven crazy by Google's v1.0 Python Spreadsheet library's lack of support for insertion based on case-sensitive row names (See http://code.google.com/apis/spreadsheets/data/1.0/developers...). There is no documentation regarding the requirement that the row name must contain only lower case characters. The .NET library is v3.0 and appears to offer much greater support for this type of basic functionality.
Furthermore, try to keep all of your API libraries up-to-date. For example, I was almost driven crazy by Google's v1.0 Python Spreadsheet library's lack of support for insertion based on case-sensitive row names (See http://code.google.com/apis/spreadsheets/data/1.0/developers...). There is no documentation regarding the requirement that the row name must contain only lower case characters. The .NET library is v3.0 and appears to offer much greater support for this type of basic functionality.
Amazon's product advertising API is nice. You can't help but get startup ideas browsing through the documentation.
While this doesn't directly answer your question, I've found this to be helpful in the past: The Little Manual of API Design - http://chaos.troll.no/~shausman/api-design/api-design.pdf
I also like this josh bloch google tech talk video "How to design a good API and why it matters.": http://www.youtube.com/watch?v=aAb7hSCtvGw
awesome. I've been looking for something that talks about api design...
Twitter -- it's a popular service, and there are libraries for most of the languages I've tried to write Twitter-related applications in.
Tumblr -- it's simple, it's clean, it returns a Tumblelog as XML over an HTTP request. You can also write posts over HTTP as well.
Tumblr -- it's simple, it's clean, it returns a Tumblelog as XML over an HTTP request. You can also write posts over HTTP as well.
My favorite is Flickr API
http://www.flickr.com/services/api/
Provides a lot of functionality. Basically anything you can do on the website you can do through the API. The names of the calls are intuitive. Provides different formats.
And most importantly has libraries available for different languages that will make the calls for you.
http://www.flickr.com/services/api/
Provides a lot of functionality. Basically anything you can do on the website you can do through the API. The names of the calls are intuitive. Provides different formats.
And most importantly has libraries available for different languages that will make the calls for you.
Take a look at Webmachine http://bitbucket.org/justin/webmachine/.
If you're writing a RESTful API try using webmachine. At the very least, you'll feel like you're writing the best API ever.
*NOTE: I have no relation to webmachine, just really impressed with the elegance how it is written and the API's it help produce.
If you're writing a RESTful API try using webmachine. At the very least, you'll feel like you're writing the best API ever.
*NOTE: I have no relation to webmachine, just really impressed with the elegance how it is written and the API's it help produce.
A good test is how easy it is to get started. If you can just make a call to curl to get started, awesome.
If things change without warning, that is bad.
If the site is down often, that is bad.
While users are awesome, and it is great to have a developer community, depending too much on them to do your QA is asking a lot.
If things change without warning, that is bad.
If the site is down often, that is bad.
While users are awesome, and it is great to have a developer community, depending too much on them to do your QA is asking a lot.
I really admire the Sun Kenai (Cloud) API:
http://kenai.com/projects/suncloudapis/pages/HelloCloud
It's a delightfully clean RESTful JSON API.
http://kenai.com/projects/suncloudapis/pages/HelloCloud
It's a delightfully clean RESTful JSON API.
I think Twitter's is great, and digg's isn't half bad either.
On the other side of the coin, Google's GData APIs (e.g., Calendar, YouTube), Paypal and Facebook are cumbersome IMHO.
On the other side of the coin, Google's GData APIs (e.g., Calendar, YouTube), Paypal and Facebook are cumbersome IMHO.
Any of Amazon's APIs - Product Advertising, AWS, et al.
I recently integrated with Zendesk and it was painless. Simple and straightforward.
http://www.zendesk.com/api
http://www.zendesk.com/api
Not SOAP :) It's a pain to consume compared to POX (plain old XML) or JSON.
a sub-question: could someone comment on other types of apis like windows (win32) or posix api?
I love developer friendly APIs.
I want to model ours after a great one. What are some of your favorites?