Lesson 1 / 27

What Makes an API Good

List the qualities of a well-designed API and why the contract matters more than the code behind it.

An API is a promise

An API is the contract between the people who build a service and the people (or programs) who use it. Once clients depend on it, you can change the code freely but not the promise. A good API is easy to learn (it behaves the way people guess), consistent (the same names, formats and errors everywhere), hard to misuse (safe defaults, validation, clear errors), well documented and evolvable (you can add to it without breaking existing users). Design from the consumer's point of view: ask what job the caller is trying to do, then shape resources and operations around that, rather than exposing your database tables or internal classes.

Design for the consumer

An API is a product with a contract: clear resources, predictable behaviour and room to evolve.

Four qualities: clear, consistent, safe, evolvable.
Figure 1.1 — Clear, consistent, safe and evolvable.

A restaurant menu

The menu is the contract: dish names, prices and descriptions. Customers do not need to know the kitchen layout, and the chef can change recipes as long as the dish matches its description.

Write the docs before the code

Sketching example requests and responses first exposes awkward naming and missing cases while they are cheap to fix. Ask a teammate to try to use the API from the sketch alone.

Quick check: Why can you change the code behind an API freely but not its behaviour?

  • Behaviour is always random
  • Code is secret and cannot be edited
  • Clients depend on the contract, so changing behaviour can break them
  • Because HTTP forbids it
Answer

Clients depend on the contract, so changing behaviour can break them — The observable behaviour is the promise; implementation details are private.