What makes an API good

An API is good when people can use it correctly without reading the source code and without asking you questions. That sounds obvious, but it leads to concrete design rules.

Predictability

If GET /bookings/42 returns a booking, a developer will guess that GET /customers/7 returns a customer and GET /bookings?customer_id=7 lists that customer's bookings. Every place where your API breaks a pattern, someone will make a mistake. Consistency in naming, casing, date formats, pagination and errors matters more than any single clever decision.

Safety under failure

Networks fail. Mobile apps lose connection in tunnels, load balancers time out, clients retry. A good API makes retries safe: repeating a request does not create a duplicate booking or charge a card twice. We spend a whole section on idempotency because it is where many real incidents come from.

Evolvability

Requirements change. A good API can gain fields, endpoints and features without breaking existing clients. That requires some discipline from day one: never removing or renaming fields without a deprecation process, never changing the meaning of an existing value, and clients that ignore fields they do not know.

Honest errors

When something goes wrong, the API should say what happened, whether the client can fix it and whether retrying might help. A 500 response with an HTML error page is not an error format.

REST, loosely

REST is an architectural style described by Roy Fielding. Most APIs called RESTful today follow a practical subset: resources identified by URLs, standard HTTP methods, JSON representations and meaningful status codes. That pragmatic style is what this course teaches. We will not argue about purity; we will focus on what makes an API reliable and easy to use.

Our case study

We design the API for Slotly, a booking platform where businesses publish services and time slots, and customers book them. It has customers, businesses, services, slots, bookings and payments. That is enough complexity to meet real design problems, such as overlapping bookings, partial failures and long lists, without getting lost in domain details.

In the next lesson we review the parts of HTTP that matter most for API design.