Foundations · Lesson 02

What makes an API good

If an API is a contract (Lesson 01), then a good API is a contract people enjoy depending on — easy to learn, hard to misuse, and safe to evolve. These qualities aren't taste; they're the exact things interviewers probe when they say "critique this API."

The qualities of a good API

A useful mental checklist — every interview critique maps onto one of these:

Design-first vs code-first

There are two ways to arrive at a contract, and the order matters:

Design-first writes the contract — typically an OpenAPI document — and gets everyone to agree before code exists. Front-end and back-end teams then build in parallel against a stable target, and you can mock the API for testing on day one. Code-first writes the server first and derives the contract from it: quicker for a solo prototype, but the public interface ends up shaped by whatever was convenient internally — exactly the inside-out trap.

The API design lifecycle

An API isn't a one-time artifact — it lives, changes, and eventually dies. Keeping the whole arc in mind separates designers from coders:

1. Requirements — who calls it, what do they need, what scale? (This is where every case study in this course starts.)
2. Design the contract — resources, operations, request/response shapes, errors.
3. Review & agree — consumers sanity-check it before code is written.
4. Build & document — implement to the spec; docs and examples ship with it.
5. Evolve — add capabilities without breaking existing callers (versioning, additive changes).
6. Deprecate — sunset old versions gracefully, with notice and migration paths.

Under the hood: a concrete BEFORE → AFTER endpoint redesign

Saying "design for the caller" is abstract. Here is a real endpoint redesign — starting from what a code-first developer might ship, mapping each problem to a quality from the table above, and showing the corrected version with the reasoning.

BEFORE — the inside-out version:

# What a junior developer might ship after building the DB schema first

POST /api/doUserStuff
Content-Type: application/json

{
  "usr_tbl_id": 42,           // ❌ DB column name leaked into contract
  "action": "deactivate",    // ❌ verb in body; HTTP method unused
  "ts": 1750000000           // ❌ Unix epoch; not human-readable, not ISO-8601
}

# Response — also broken:
HTTP/1.1 200 OK
{
  "res": "ok",              // ❌ "res"? what does that mean?
  "err": ""               // ❌ empty string to mean "no error" — use the status code
}

AFTER — the redesigned version:

# Resource-oriented, uses HTTP semantics, hides internals

PATCH /v1/users/42
Content-Type: application/json

{
  "status": "inactive"      // ✓ field name is a concept, not a column
}                             // ✓ PATCH = partial update; the verb is the HTTP method

# Response:
HTTP/1.1 200 OK              // ✓ status code carries success/failure — no body parsing needed
Content-Type: application/json

{
  "id": 42,
  "status": "inactive",
  "updated_at": "2025-06-15T10:30:00Z"  // ✓ ISO-8601 with timezone
}

# Error case — returns a machine-readable problem object:
HTTP/1.1 422 Unprocessable Entity
{
  "error": "invalid_status",
  "message": "status must be 'active' or 'inactive'"
}

The AFTER version satisfies all six qualities: it is easy to learn (standard HTTP semantics), hard to misuse (wrong method returns 405, wrong value returns 422 with a clear message), consistent (every user endpoint follows the same /v1/users/:id + HTTP method pattern), minimal (one field to express intent), evolvable (add fields to the response without breaking callers), and documented (the response shape is self-describing).

How to debug & inspect it — reviewing an API for quality

Reviewing an API for the qualities above is an active skill, not a vibe check. The process below applies equally to a PR review, a design session, or an interview critique question.

Run a linter first. If the API has an OpenAPI spec, Spectral catches the mechanical issues (missing descriptions, undefined response codes, wrong types) before human review. Install and run it against a spec file:

After the linter, walk each endpoint through this structured checklist:

Review checklist (use this in a code review or interview):

1. Does every path use a noun resource, not a verb? (No /doThing or /getUser.)
2. Does the HTTP method match the operation's semantics (safe = GET, idempotent mutation = PUT, partial update = PATCH)?
3. Are all status codes semantically correct — 2xx success, 4xx client errors, 5xx server errors?
4. Does the response body hide all storage/internal details (no column names, no ORM artefacts)?
5. Are all timestamps ISO-8601 with a timezone? Are all IDs strings (not integers that overflow JSON in some languages)?
6. Is there a consistent, documented error response shape across every endpoint?
7. If there's an OpenAPI spec: does spectral lint pass clean? Are all operations described?

Sources & further reading

• Microsoft — Web API design best practices
• Google — API design guide
• OpenAPI Specification (the design-first contract format)