A few comments:<p>> valuable service<p>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.<p>> Design<p>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.<p>> Documentation<p>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<p>Addenda: I have two other considerations, somewhat unrelated:<p>- 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.<p>- Support for JSON is usually appreciated (by me anyways).<p>Edit: Fixed typo (without->with)
I'll add two points that I think are more important than any that have been mentioned so far.<p>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.<p>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).
One thing not mentioned here: discoverability.<p>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.<p>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.
I agree with the list and I would like to add a couple of points to it.<p>1. don't return error formats in a different data format (e.g. xml error response with a json api)<p>2. don't use custom request signing (hey, mixpanel and seomoz)<p>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.<p>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.<p>5. use REST<p>6. be fast<p>7. provide as much nested data as you can without violating 6<p>8. maintain your own client libraries<p>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 don't think the points mentioned are very discriminating. Planning, design, documentation... Aren't these traits indicative of all "great" software?<p>Maybe the best way to express what makes an API great is to lead with an example. Show me a great API.
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.