Ask HN: What makes an API good?

Consistency, predictability, documentation, reliable sample client in a couple of popular languages (e.g. PHP, Python, Ruby), well abstracted.

Documentation.

You might want to check out The Little Manual of API Design:

http://www4.in.tum.de/~blanchet/api-design.pdf

Documentation is 1000x above anything else. This includes sample project(s).

Documentation is without question the deciding factor of whether I'll use a service.

Besides that, I care about support channels, adherence to standards (i.e. correct HTTP status codes), and as few hoops as possible to jump through to start (i.e. a curl command to get my auth key, and away I go)

The main thing about creating a good API is that you have a good relationship and good communication with the consumers of that API. I've seen a lot of people making internal APIs inside companies treat it as another way to throw something over a wall.

There's very little universal about a "good" API design. Even response time might not matter if your users aren't using it synchronously. Best way to make an API is to have a plan to support old versions, release something early, see what people make of it and incorporate their improvements. Worst way to make an API is to try and think of everything before you start - you will fail and you'll take a long time

One vote for good documentation.

Not just a link to the Javadocs; preferably a "getting started" page that covers the most common use cases with plenty of plug and play examples (if such a thing is even possible in your case).

Also, getting back to the API reference, I'm grateful when there is a roadmap or overview of the class/package structure so I don't have to crawl through the entire thing.

Would be great if you shared what you've compiled as well. Thanks.

I highly recommend this ~hour long talk given by Josh Bloch a few years ago, it is quite good and gives plenty of concrete examples: https://www.youtube.com/watch?v=aAb7hSCtvGw

Aside from common things like "being useful" the key aspects of a good API (to me) are:

1. Expose 2. Wrap 3. Consistency

Expose what's going on under-the-hood. For example, an HTTP.Get function may do what's needed 98% of the time, but if you don't expose requests, sending, keep-alive, etc. then I won't be able to do the last 2% when I really need it. Part of exposing is factoring your functions well.

Wrap what's exposed to handle the most common cases. If I want to perform a GET request, I shouldn't be required to create a request, open a socket, issue the request, parse the response, follow redirects, etc. There should just be a simple HTTP.Get function that does all that for me with the common options as arguments.

Finally, the API should be consistent. Consistency covers a range of topics. The API should be consistent within itself: consistent naming, modules, etc. It should be consistent within the environment (e.g. don't use underscored function names in Go). But consistency also means future releases shouldn't break existing code unless absolutely necessary.

Versioning. Also, make sure that you're committed to supporting old versions of your API for the foreseeable future (the actual time period depends on the company - for Google, 20-30 years, while 3-5 years for a startup).

1) URL construction: KISS (Keep It Simple Stupid), or as Einstein said, "Everything should be made as simple as possible, but no simpler."

2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation.

3) Response Time: meh. If your at or around 100ms you don't need to worry to much. If people want ~50+ calls per second, then ask them what their use case is, or have them pony up money. Then worry about response time.

4) Flexibility: Largely over rated. You can waste a ton of processing power trying to figure out what the user meant to say. Most of it is wasted, if their query doesn't make sense return an error. Your performance will go up. This hooks into documentation, if your documentation is easy enough to understand you won't have to fuzz the queries.

5) Code Samples: See documentation.

Agree with notjosh on this -- so what makes documentation good?

I like it when APIs offer good filtering options for searches. When all you have is basically "here is a list of things" + "here is a single thing with an ID", all you end up doing is scraping the entire list to do fun things.

Some things that irk me:

0. JSON. Use JSON.

1. Version your API

2. Any numerical value whose precise value you care about, send as a string.

3. Any ID should be sent as a string.

4. Any timestamp should be sent as RFC3339 UTC.

5. Any data whose numerical value matters (i.e., must properly include NaNs, whatever) should be sent as an encoded base64 blob.

6. Properly support HEAD, PUT, PATCH, OPTIONS.

7. Send back your response as human-readable JSON, with newlines and tabs. If you can't afford the bandwidth (protip: you can), then you shouldn't be using a text format anyways.

8. Allow me to change replies using accept headers and extensions on the URI. Document the order of precedence.

9. Understand the limits of the REST mental model for handling things--don't be afraid to have a few "ugly" endpoints.

If that data is ever to be viewed by a human you should focus on presenting the data in such a way that it is as easy as possible to display on the screen, if the process of getting the data to the screen is not easy the vast majority will either try to find an easier product to work with or just give up on trying to find a solution to that problem. (IT guys have a lot on their plate, and mountain of forgotten projects because they didn't have the time)

At 18F (a digital services consultancy within the US federal government), we've drafted API Standards[1]. They're a set of recommendations, rebuttable presumptions, and bright line rules that we expect our APIs to adhere to. For an organization that may offer several APIs, having a set of standards will help ensure, among other things, baseline quality and consistency.

[1] https://github.com/18f/api-standards

Phil Sturgeon's "Build APIs You Won't Hate" is a fantastic resource. It is directed towards PHP but the ideas are obviously transferable.

https://leanpub.com/build-apis-you-wont-hate

Agreed with all the previous comments.

URL Design is key. I often refer to the naming chapter of Uncle Bob's Clean Code book for this. This also helps with consistency and predictability, which in turn, makes writing docs easier.

I've got an API Design Readlist, which I've added this thread to. http://readlists.com/6c5c6009/

I highly recommend the following talk by Joshua Bloch: "How to design a good API and why it mattes" [1].

Key points:

- When in doubt, leave it out - you can never remove things from an API but always add to it.

- Write several clients of the API to get a good feel how its used. Three is usually enough, one is not.

[1] https://www.youtube.com/watch?v=aAb7hSCtvGw

Simplicity. As a consumer of your API I should not have to do anything I don't need to. The worst thing is when you have to jump through hoops to deal with an API that was clearly designed for the implementer's convenience, not yours.

The Heroku platform team has a good document about their API design guidelines:

https://github.com/interagent/http-api-design

Consistency. pick a convention and keep doing things that way, always and everywhere.

If its a Java or object-oriented framework or library - follow SOLID principals and limit dependencies. Make it unit testable. Try to make it consistent - calls to get one type of object should be similar to ways to get other types of data, etc. Functional approach to the interfaces - pass in required arguments, get back result. Don't require user/developer to create several configuration or factory objects before they can call a simple method to get some data, etc. Don't require the use of dependency injection frameworks or other complexities. If its web-based API return data as simple JSON or XML without overly complex namespaces, etc. Name things consistently - the names of response objects and properties should be the same as the corresponding inputs, etc. Copy - look at a successful API or library which does something similar - then copy the way it works and the way its documented. Especially if the users/developers already know how to use that one...

I think it depends upon the use cases of the API, but if you want someone to be able to build snappy and fast "apps" using your API rather than just facilitating movement of data in/out for an integration with another piece of software, I think granularity is important.

Having built our front end using AngularJS, we are the first users of our own API and that has driven it's design. In order to make things quick, we really needed to trim down response payloads in some cases which kind of deviates from standard CRUD patterns in some areas.

This has come at the expense of good documentation (we have a lot more methods now and having good examples of all of them will be expensive) and consistency--things are not very uniform anymore. However, as an API consumer I'd rather have the API give me too many options rather than too little. Our API has gone from "pretty" to "very functional".

You can find these slides interesting:

http://slideshare.net/guestbe92f4/how-to-design-a-good-a-p-i...