# What Makes an API Good — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/pr-what-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.](assets/figures/api-design/section-1-map.svg) — 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.

**Quiz:** 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
- [x] 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.