
Ask HN: Who makes the best APIs? - breck
I'm writing a first draft of an API for Jobpic.com. Mostly just for fun, I have a friend who is going to write an app for us.<p>I love developer friendly APIs.<p>I want to model ours after a great one. What are some of your favorites?
======
staunch
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.

------
Barnabas
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.

------
rbritton
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.

------
hellotoby
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.

------
babyshake
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.

------
mullr
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.

------
tptacek
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.

------
jasonkester
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.

------
_pius
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.

------
white_eskimo
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...](http://code.google.com/apis/spreadsheets/data/1.0/developers_guide_python.html#addRow)).
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.

------
chaosmachine
Amazon's product advertising API is nice. You can't help but get startup ideas
browsing through the documentation.

------
vibhavs
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>

~~~
throw_away
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>

------
scottjackson
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.

------
elviejo
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.

------
roder
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.

------
ivankirigin
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.

------
kogir
I really admire the Sun Kenai (Cloud) API:

<http://kenai.com/projects/suncloudapis/pages/HelloCloud>

It's a delightfully clean RESTful JSON API.

------
qeorge
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.

------
mumrah
Any of Amazon's APIs - Product Advertising, AWS, et al.

------
chrisbolt
I recently integrated with Zendesk and it was painless. Simple and
straightforward.

<http://www.zendesk.com/api>

------
nsfx
Not SOAP :) It's a pain to consume compared to POX (plain old XML) or JSON.

------
leej
a sub-question: could someone comment on other types of apis like windows
(win32) or posix api?

