I love how you can connect a few APIs and build something completely new. The thought of computers talking to computers is amazing and APIs are a big part of the open web. Over the years I realised a few things about API design best practices: We need to design APIs for humans, not computers.
What made Stripe great
Stripe is not just a unicorn. It’s one of the biggest unicorns at almost a $100 billion evaluation! But Stripe didn’t win by undercutting everyone else with cheaper prices. Instead they built something their customers loved. A big group of those customers were developers trying to bootstrap something.
Stripe was the first payment processor that didn’t make you feel stupid
Stripe understood something other payment providers didn’t. Before Stripe most other payment providers seemed a pain to work with. Setup and integration was bureaucratic, complex and lacking documentation and support. Stripe changed all that. They built a payment provider that didn’t make you feel stupid. It empowered their customers and focused on the developer experience. In that the built a strong and vocal following for their brand, something no ads campaign can reproduce.
Building a great user experience for APIs
When we talk about the user experience of an API we have to start at the very beginning, well before any API keys are issued or any request is sent. What’s your first interaction with the Stripe API? You probably hammered some search term into Google DuckDuckGo and ended up at a landing page. This is the first interaction. If this landing page can’t explain the purpose of your API in one single sentence it’s already game over for your potential customer.
Make it easy to discover and understand your API
The first step to build an API your consumers love is to make it a bliss to discover and explore it before you have to set it up. From a landing page your potential API consumer will want to explore documentation.
Your API documentation is core to your API. Don’t just document what each API endpoint does. Put yourself into the shoes of your consumers: What’s their state of knowledge? What do they want to accomplish with your API?
Walk your users through some use cases of your API in a Getting started guide and make it interactive. Next.js does this by giving the reader a quick and easy quiz to engage them at the end of each section. API documentation tools like Stoplight and Apiary make it easy to execute a fake request to see how the requests and responses of your APIs look and feel.
API design best practices to make your API discoverable:
- Your landing page should explain your API in one simple sentence. This is the start of your API user experience.
- Create guides and tutorials to onboard your API consumers
- Make your documentation interactive with quizzes or executable request-response examples
Make it easy for developers to integrate your API
Again, put yourself into the shoes of your API consumer. When you first start out using a new API you will certainly encounter an error. As an API designer you can make those errors either hard to understand or self-explanatory. There’s a wide range of HTTP status codes to make that easier, but you shouldn’t stop there. A 400 Bad Request error can have many reasons, so why not add the exact field that failed the validation to the HTTP body? This will save valuable engineering time and create this blissful API experience we’re after.
Prevent your consumers from committing mistakes
User experience is not all about what you can do with an API. It’s also what you can not do with your API. In security the principle of least privilege (PoLP) mandates that every user’s privileges are limited to only those needed to do the job at hand. We can extend this not just to privileges but to functionality in general: Don’t expose API functionality that you think someone might need. Instead try to understand their use cases and only offer the necessary through your API. Once your API consumers understand that you also got their back and won’t let them make mistakes unnecessarily you’re on track to gain some loyal customers.
API design best practices to make your API easy to integrate:
- Return human-readable error messages
- Prevent them from committing mistakes by limiting privileges and functionality
Designing your API consumer journey
If you want to limit your API functionality to the necessary minimum you need to understand your consumer’s goals. They’ll first authenticate, then they might call an index endpoint to go on to manipulate a record and so on. This is the material you should be writing guides and tutorials about. But don’t just map out a superficial user flow. Think how the different endpoints and responses work together. Think about which data you can include in your search results to save on consecutive results. Give your user the chance to filter and order results so they have to request as little unnecessary data as possible. Design your pagination in a way that helps them.
Last but not least be consistent with your naming. It does not make sense to call an entity author once and then having to user this as creator with slightly different attributes on another endpoint.
API design best practices for creating an API consumer journey:
- Include relevant data to reduce consecutive requests
- Allow filtering and sorting to only return relevant data
- Be consistent in naming things
API design best practices help you build APIs for humans
To build great APIs design them for humans, not computers. When you talk about a programming interface it’s best to think about a programmer interface because there’s a human on the other side discovering, integrating and eventually falling in love with your API.