

Ask HN: What makes a great API? - frankdenbow

What does it take to make a great API in a developer's eyes? I am doing a talk and would love to get some feedback on the types of things you all think about when choosing APIs to work with.<p>Some things include documentation, speed to hello world, RESTfulness, simple authentication, aligned incentives, helpful examples, and customer service. What do you think?
======
zemo
Make authoring my own client in my own language straightforward. If you say
"see our reference implementation in [some programming language I'm not
using]" I'll be very, very irate. This is the kind of thing I'm talking about:
<http://docs.recurly.com/recurlyjs/signatures/spec/>. Expanding on that
particularly egregious example: a handful of unit tests is not a
specification, and if you want a variety of developers to use your API you
can't have its documentation be a set of unit tests. A set of unit tests in a
third-party DSL is even worse.

Your documentation should be language agnostic. Everything should be described
in regards to HTTP methods, not some aspect of your language, your language's
standard library, or, god forbid, some third-party library in your language.

If you DO expect users to rely on a reference implementation, it should be as
generic as possible. I'm not a [insert language here] programmer and I don't
want to have to learn the ins and outs of [your sandboxing tool] and [your
library management tool] and [some fistfull of random third-party libraries]
in order to install and run your samples.

Always respond with the requested format, even on errors. Yes, I am advocating
that you put a diaper (i.e. a try ... catch block that catches all errors) on
your API endpoint. Diapers are generally a bad idea, but if I send you a json
request that, for whatever reason, throws a server-side error, please return
the error information in a json-parsable manner. django-piston is guilty of
not returning json-parsable error pages, and it has the second-most followers
of all bitbucker repositories. <https://bitbucket.org/jespern/django-
piston/wiki/Home>

If possible, write sample clients on a variety of popular languages. Put your
client on PyPi or RubyGems or npm or Pear or CPAN or whatever, just don't
half-ass it.

Know your audience. It's perfectly possible that your target audience doesn't
actually give a shit about RESTfulness and they're perfectly happy using SOAP
or (gasp!) XML-RPC. Those things may not be "cool" in the buzzwordy world of
dynamic scripting languages, but the reality is that they're still standards
and yes, people do use them.

Be mindful of how insular HN is and where its interests lie; the HN userbase
is representative of the HN userbase, not software developers as a whole.
There's a creaking leviathan in the world of "enterprise" software whose
foundation lies in things like Java and .NET and where mechanisms like SOAP
and XML-RPC are still in use. SOAP is neither useless nor mandatory; it is
used by a subset of the software development community, some of whom may be
more than willing to give you good money to integrate with their services, if
only you'd let them.

------
billswift
From the highest level view:

1) Reliability - it can be counted on to do its job.

2) Consistency - it does it in the same, or at least the same small set of,
ways each time.

3) Clarity and Discoverability - it is easy to see or find out what it does.

~~~
neinsun
Documentation?????

~~~
billswift
I would put adequate documentation as part of clarity and discoverability,
both because they serve the same end and because the inherent clarity and
discoverability can increase or decrease the amount of documentation needed to
effectively use the API. So maybe I should have said "clarity,
discoverability, and documentation".

------
kirps
Documentation and ease of use. The API should function at the highest level
possible. I should be able to call the service with concise and powerful
statements. The beauty of an API is the ability to quickly build further upon
something that has already been done. If I have to go ten rounds with it to
get it to work, you've missed the boat.

In that same vein the documentation should be clear and to the point. See
Amazon Flexible Payments as an example of what NOT to do. Ambiguous docs with
tons of circular linking etc. made me want to kill myself and did end up
killing my project. Just my .02.

------
LeBlanc
One thing that works great is to build a sandbox tool that lets your users
make real API calls with their credentials from your API documentation.

Facebook, Stripe, and WePay have done this. It makes integration much easier
when you can test API calls before writing any code.

------
karterk
Others have pretty much summarized my thoughts, but I will add one more to the
list: information on rate limiting. The API, if it has rate limits should
allow me to track that.

------
gfox
Your list is a great place to start. I would add _clarity of purpose_ (too
many just say _help build back ends_ )

------
bmelton
Documentation & Reliability.

I can suffer through any problem with a remote API so long as the
documentation is clear, thorough and contains relevant examples. Stripe's API
documentation is about the best I've seen in recent years.

They get bonus points for making the 'cut and paste' examples _actually_ cut
and pastable, as they don't have instances of
"stripe.com/method/<your_api_key_here>", and instead of have
"stripe.com/method/my_actual_api_key", which is super convenient.

Perhaps the only thing that good documentation can't trump is unreliability.
This includes (obviously) an API that doesn't always return the right values,
or that sometime's fails, but also includes rapidly changing API protocols.

Take the time to think about your APIs early, and try very hard to keep them
from changing once they're established. Nobody wants to have to refactor their
code because you refactored yours.

