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).
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.
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.
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).
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.
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
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.
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.
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.
20 comments
[ 3.6 ms ] story [ 49.8 ms ] thread> 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)
The "valuable service point" struck me now. I'll refactor that section on the blog soon.
POST /users
GET /users
PUT /users {:id => 2, ....}
GET /users/2
GET /users/2/friends
POST /users/2/friends
etc
Maybe the best way to express what makes an API great is to lead with an example. Show me a great API.
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.
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).
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.
Martin Fowler has a good article on the Richardson Maturity Model, and what each part means: http://martinfowler.com/articles/richardsonMaturityModel.htm...
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
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.
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.