
What makes a great API ? - kirang1989
http://kirang.in/2013/11/07/what-makes-a-great-api/
======
abraxasz
A few comments:

> valuable service

I'd think that what makes a good api should be characterized independently of
what makes a good service. You can have a useless service, with a fantastic
api. No one is going to use it, maybe, but the api itself can still be
objectively seen as being good.

> Design

I agree with most of the points, although I'd say that the single most
important part of the design is ease of use. I'm not a professional software
engineer, so I don't have a good appreciation for the other elements.

> Documentation

Now that is the most important part for me. I recently had to use the API of a
service I won't name. It was a disaster. The API was documented, but the
documentation was basically unreadable and confusing. It took me a long time
to figure out how to work with it. A good documentation, with extensive
examples can save the user an awful lot of troubles

Addenda: I have two other considerations, somewhat unrelated:

\- The last API I had to deal with use OAuth. I assume that there's a module
or package for it in most languages. But this is the kind of thing you want to
check, because if your language of choice doesn't have it, then good luck
implementing it.. (rule number one of cryptography: don't write cryptography
code yourself). I'm sure there are other examples of tiny details like this
that make certain languages harder to use.

\- Support for JSON is usually appreciated (by me anyways).

Edit: Fixed typo (without->with)

~~~
kirang1989
Thank you for your thoughts and suggestions ! :)

The "valuable service point" struck me now. I'll refactor that section on the
blog soon.

------
fcanas
I'll add two points that I think are more important than any that have been
mentioned so far.

1) A good API is hard to misuse. – Documentation is great, but what's even
better is when the naming conventions and responses from the API are so well
named and their purposes are so obvious, that it's hard to misuse.

2) A good API is helpful and informative when you've misused it. – Sent in an
invalid key? The response should say so, and not just return an anonymous
error. Is your request missing a required header field? A required parameter?
An incorrect type for a parameter? Unused parameters? Yes, good documentation
can help with these issues. But one of my biggest problems with documentation
is that you can't look up what you don't know you need to look up (especially
when there aren't any good tutorials).

------
danpalmer
One thing not mentioned here: discoverability.

As there are more and more APIs, more devices, and in general more complexity,
computers should be talking to each other and figuring things out between
themselves more. Right now almost all APIs require developers to explicitly
code the interaction details. If 'RESTful' web services were actually
'RESTful' (i.e. reached level 3 on the Richardson maturity model) then we
might be able to do that.

People keep saying that HATEOAS isn't ready for use yet, I'd say the only
reason for that is that no one is using it. I would consider a level 3
qualifying web service to be technically far superior to the majority, and I
would be more likely to use it.

~~~
kirang1989
Any good resources to read more about "discoverability" that you'd recommend ?

~~~
danpalmer
The original thesis on REST by Roy Fielding is a good start, to understand the
real motivation behind creating it.

Martin Fowler has a good article on the Richardson Maturity Model, and what
each part means:
[http://martinfowler.com/articles/richardsonMaturityModel.htm...](http://martinfowler.com/articles/richardsonMaturityModel.html)

Finally, for an example of why HATEOAS is a good thing, and why APIs should be
at level 3 on the RMM, Jon Moore has a good talk on Hypermedia APIs here:
[http://vimeo.com/20781278](http://vimeo.com/20781278)

As far as I am aware, there are very few companies actually applying these
principles. GitHub is doing something close to it in their API, and I have
heard that Google uses this sort of system for their APIs extensively on
internal projects. In terms of new-web-API-startup like companies,
Twilio/Stripe et. al, I have yet to see many take it this far.

~~~
kirang1989
I see. Thank you for the resources :)

------
cynusx
I agree with the list and I would like to add a couple of points to it.

1\. don't return error formats in a different data format (e.g. xml error
response with a json api)

2\. don't use custom request signing (hey, mixpanel and seomoz)

3\. when rate limiting, use headers to communicate how much requests are left,
how many were made before and how many seconds until the rate is refreshed.

4\. Authentication, there's an obvious ease-of-use vs. sensitivity of the
data. but when in doubt pick basic auth (or api-token) with https and close
port 80 on the api host.

5\. use REST

6\. be fast

7\. provide as much nested data as you can without violating 6

8\. maintain your own client libraries

I agree with the comments here that documentation and consistency is a good
thing, I also agree with having an option to batch requests if you have a
rate-limit in-place.

------
adamb_
I don't think the points mentioned are very discriminating. Planning, design,
documentation... Aren't these traits indicative of all "great" software?

Maybe the best way to express what makes an API great is to lead with an
example. Show me a great API.

~~~
kirang1989
Yes, those points are general traits of all great software. But there are
still API's out there that fail to conform to those basic principles and
that's why I wanted to write the post as a checklist to self, to remind as to
what makes an API great.

~~~
RogerL
Yes, but the world is now reading ;)

I found this very simplistic, but then I didn't realize it was a checklist for
yourself. A few notes, if I may:

first, it is generally recognized that it takes 3 or so tries to get an
API/framework correct. Meaning used in 3 or so representative projects. Oh, if
you are essentially copying another API in a different language or whatever
than the hard work is done. But recognize there will be a lot of refactoring
going on in greenfield development. So you probably don't want to do big
design up front, as you will get it wrong. Accept that. I'm sure we can point
out some genius counter-example, but for us mortals the rules apply.

You touch on some of that in the post, but for me it is always the biggest,
most important thing, and it almost always get treated as the elephant in the
room that no one really acknowledges, or kind of just hand waves away, and go
off and invest 3 months of work into something that is broken and unusable
even before public release.

Second, I'm not sure you captured another vital component - that of safety.
One of the MS Press books (I forget which one) uses a vending machine analogy.
There was a vending machine in the office that had you punch in 2 numbers to
get a product. A digit for the row, another for the column. Perfectly usable,
except there was endless cursing because inevitably people would punch in the
#s in the wrong order, and get something they didn't want. The trivial fix is
to use letters for columns, and #s for rows, so the KitKat bar is A3, and the
gum is C1. Fixes are often a lot less trivial in code APIs. But you need to
design them so the user cannot easily shoot themselves in the foot. How many
hours have you struggled with a 3rd party library because it _looks_ like you
connected everything up correctly, but nothing works? The API allows you to do
things that have no meaning.

------
seivan
Consistency and logic.

POST /users

GET /users

PUT /users {:id => 2, ....}

GET /users/2

GET /users/2/friends

POST /users/2/friends

etc

~~~
iLoch
PUT should reference the object ID in the URL though.

~~~
seivan
Yup, I agree. But I just wanted to show how the params might look like.

------
jpdlla
I agree on all this points, although all of them should apply to any type of
software you build. Anyone know of great APIs of non-tech startups?

------
jeffblake
I can't remember what it was, but someone posted here before with a library to
help build clean, easy to use API Docs. The one that looks like a split-pane
with examples on one side and details on the other.

------
dreamdu5t
Documentation and consistency. I almost don't care if your API sucks as long
as it's documented well.

~~~
kirang1989
Precisely the reason why I enojoy integrating Stripe or Twilio. They've
abstracted a complex service with a beautiful API and awesome documentation.

------
AznHisoka
A great API helps me print cash.

