Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 1 · Lesson 1 · 4 min read

What Makes a Good API? API Design Principles

On this page
  1. An API is a user interface for developers
  2. Six principles of good API design
  3. Example: redesigning a confusing endpoint
  4. Design the API contract before you build it
  5. Check yourself

An API is a user interface for developers

Every API decision is felt by someone else's code for years. Rename a field and integrations break. Return errors inconsistently and every client writes special cases. Once people depend on an API, its mistakes are expensive to undo, which is why design deserves time up front.

Think of an API as a contract. Your side promises: send me this, and I'll answer with that. The developers who call it, called consumers or clients in this course, write code that trusts the promise. A web page can be redesigned overnight because people adapt; code can't adapt, so every change to the contract has to be planned.

Six principles of good API design

  • Predictable: once you've learned one endpoint, you can guess the next. Same naming, same pagination, same errors everywhere.
  • Hard to misuse: required things are required, dangerous actions are explicit, and the obvious call is the correct one.
  • Designed for the consumer: shaped around what clients need to do, not around the database tables behind it.
  • Self-describing: names and responses explain themselves; good docs fill the gaps (Day 22).
  • Evolvable: new features can be added without breaking existing clients (Day 23).
  • Secure by default: authentication, authorization and limits are part of the design, not a later layer (Days 11 to 13).
A good API is consistent, hard to misuse, focused on the consumer's task and able to change without breaking clients.
A good API is consistent, hard to misuse, focused on the consumer's task and able to change without breaking clients.

Example: redesigning a confusing endpoint

A subscription-cancel endpoint, first draft:

HTTP
POST /doCancelSub?subId=482&mode=1

200 OK
ok

Problems a client developer hits immediately:

  • A verb in the URL (doCancelSub) unlike the rest of the API's resource paths.
  • mode=1: what does 1 mean? Immediately? At the end of the billing period?
  • The response ok tells the client nothing: when does access end? Was a refund issued?
  • Retrying after a timeout might cancel twice or fail confusingly.
  • A 200 OK with a plain-text body can't carry structured error details when something does go wrong.

Second draft:

HTTP
POST /subscriptions/482/cancellation
Content-Type: application/json

{ "effective": "end_of_period", "reason": "too_expensive" }

201 Created
Location: /subscriptions/482/cancellation
{
  "subscriptionId": 482,
  "status": "pending_cancellation",
  "effective": "end_of_period",
  "accessEndsAt": "2026-11-01T00:00:00Z"
}

What changed:

  • The cancellation is modeled as a resource under the subscription, consistent with other paths (Day 3).
  • The magic number became a named, enumerated value (end_of_period or immediately).
  • The response returns the new state, so the client can update its UI without another request.
  • Creating the same cancellation twice can return the existing one, making retries safe (Day 10).

Design the API contract before you build it

  • Write the contract first: an OpenAPI or GraphQL schema, reviewed by the people who'll call it, before writing the implementation (Day 22).
  • Write example requests for the main use cases. Awkward examples reveal awkward design.
  • Follow a style guide (your own, or published ones from Google, Microsoft or Zalando) so every team's endpoints look alike.
  • Lint the contract in CI, so rules are enforced automatically.

Check yourself

Developers learn the API's patterns once and apply them everywhere; every inconsistency is a special case each client must discover and handle.

Its meaning is hidden: nobody reading mode=1 in a request or log knows what it does without the docs, and it's easy to pass the wrong number. Named values like mode=preview are self-describing, can be validated, and new modes can be added without confusion.

The client learns the new state, such as when access now ends or the new status, without guessing or making another request. It also avoids subtle bugs where the client's assumption about the result differs from what the server actually did.

Model the refund as a resource, such as POST /payments/91/refunds, so it matches the API's other noun-based paths and the refund can be read back later.

Consumers can review the shape of requests and responses while changes are still cheap, and frontend and backend teams can work in parallel against the agreed contract.