What problems are we trying to solve?

Here are my priorities, in order of importance. I think these should be your priorities too.

1. Our API fulfills our product requirements.
2. It’s sufficiently fast and stable for our expected traffic and load.
3. It’s easy to integrate into various downstream systems.
4. It’s easy to explore with simple tools like cURL.
5. It’s adaptable for future requirements that we don’t know about yet.
6. It’s pleasant to develop with.

We may ship client libraries for various languages, but ideally we don’t have to, because nothing about it is that complicated. The inputs and outputs should be simple and predictable enough that introducing a layer of abstraction just feels like a redundancy. (It’s nice to avoid additional layers of abstraction, because then there are fewer components we have to maintain. The API is the abstraction.)

Here are some things I don’t care about—problems we’re not trying to solve—in no particular order. This list is not exhaustive.

• It’s not trendy or modern.
• It’s not a drop-in replacement for some other API.
• It’s not perfectly efficient or faster than it needs to be.
• It’s not 100% discoverable (in the hypermedia sense).

JSON over HTTP

It may not surprise you to know that what we’re going to talk about is an API that serves JSON over HTTP using REST principles. It’s about as simple as you can get.

There are other, newer options: a graph-based interface like GraphQL, or an RPC-based interface like gRPC. I do not recommend adopting these technologies. They certainly have their benefits, but for my priorities, they all pale in comparison to the most obvious and “boring” choice. If your API is unexceptional, but it helps your users do their jobs quickly and efficiently, you’ve succeeded.