Ask HN: What makes an API good?

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.

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.

Very true, but it needs to be a specific type of documentation - namely something that explains how to use the API rather than what the API endpoints are. By sitting down and writing about what's needed to get the most out of the API, as well as writing extensive code examples, you're forced to think about how people are going to use the API. Any problems, quirks or bugs should be obvious at that point because you're using the API as it'll be used by other developers. Simply listing the endpoints with what parameters they need and things they'll return won't make your API better.

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.

been in this position! I feel bad thinking about it now!