API Design / Contract-First

Test what you designed, not what you accidentally shipped

Testability starts with design. Five principles of HTTP API design, each paired with an assertion that verifies it, plus the contract-first vs code-first workflow comparison that determines whether your tests can catch drift before users do.

Sister lab: the /contract lab teaches tools to VERIFY contracts (Pact, Schemathesis, openapi-diff). This lab teaches how to DESIGN the contracts worth verifying. Design first, then test.

1. Resource modeling — nouns, not verbs

Model the domain as resources (nouns). HTTP methods are the verbs; URIs name the things, not the actions.

Bad

POST /createUser
POST /getUserById
POST /deactivateUserAccount
POST /sendPasswordResetEmail
POST /markOrderAsShipped

Good

POST   /users
GET    /users/:id
PATCH  /users/:id           { "status": "deactivated" }
POST   /users/:id/password-resets
PATCH  /orders/:id          { "status": "shipped" }

# Nested relationships: POST /users/:userId/orders
# Actions as sub-resources: POST /orders/:id/refunds

How to test for it: URLs contain only nouns (except well-known actions: /search, /ping). HTTP method expresses the action. Each resource supports the same method semantics across the API (GET always reads, POST always creates a subresource).

2. Versioning — path vs header, and when to bump

Pick one scheme and commit. Path versioning (/v1/) is cache-friendly; header versioning is content-agnostic. Never mix.

Bad

# Mixing schemes — clients confused about which wins
GET /v1/users                  Accept: vnd.api+json;v=2
GET /users?api_version=3&legacy=v1
GET /beta/users-new-improved

Good

# Path versioning (common, cache-friendly)
GET /api/v1/users
GET /api/v2/users              # breaking change → new major

# OR header versioning (one scheme throughout)
GET /api/users
  Accept: application/vnd.example.v1+json
GET /api/users
  Accept: application/vnd.example.v2+json

# Deprecation signal (RFC 8594)
GET /api/v1/users
  Deprecation: true
  Sunset: Sat, 31 Dec 2026 23:59:59 GMT
  Link: </api/v2/users>; rel="successor-version"

How to test for it: Every major version change introduces a new major version number. The server emits Deprecation + Sunset headers on deprecated versions. Clients on the old version get a response, not a 410 Gone, until the documented sunset date.

3. Evolution rules — what breaks, what doesn't

Adding optional fields and new endpoints = minor/patch. Renaming, removing, reordering, changing types = major. Assume clients ignore unknown fields; never assume they handle missing ones.

Bad

# v1 → v2 breaking changes without version bump
v1: { "id": 1, "name": "Alice" }
v2: { "id": "u_1", "fullName": "Alice" }    # id type changed, rename

# "Small change" that silently breaks clients
Renamed `email` → `emailAddress` in response — clients reading `email` see undefined
Removed `isActive` field — logic branching on it now hits null
Tightened validation: `password` now min 12 chars (was 8) — existing valid users blocked

Good

# Additive-only in a minor release
v1.0: { "id": 1, "name": "Alice", "email": "a@b.c" }
v1.1: { "id": 1, "name": "Alice", "email": "a@b.c", "phone": "+1..." }  // new optional field

# Major bump for any breaking change
v2.0: { "id": "u_1", "name": "Alice", "email": "a@b.c" }
  -> documented migration guide + deprecation of v1 for 6 months

# "Add new, deprecate old" — coexistence for transition
v1.2: { "email": "a@b.c", "emailAddress": "a@b.c" }    # both present
v1.3: `email` marked deprecated in OpenAPI, both still present
v2.0: only `emailAddress` (6 months after v1.3 ships)

How to test for it: Contract diff tool (openapi-diff, Schemathesis) runs on every PR and blocks on breaking changes without version bump. Client written against v1.0 still parses v1.5 responses (ignoring unknown fields). New required fields appear ONLY in new versions.

4. Error envelope — shape + codes, not just messages

Errors are data. Give them a stable shape, a machine-readable code, a human message, and per-field details. Clients branch on code, display message, not the reverse.

Bad

# Different shape per endpoint = client cannot branch reliably
400: { "error": "Invalid email" }
400: { "errors": ["email is bad"] }
400: { "message": "Something went wrong", "status": 400 }
400: "Validation failed"

# Message-as-API — translating it breaks the client
if (err.message === "Email already exists") { ... }  // i18n breaks this

Good

# Stable envelope on every 4xx / 5xx
HTTP/1.1 409 Conflict
Content-Type: application/problem+json     # RFC 7807

{
  "type": "https://api.example.com/errors/duplicate-email",
  "title": "Email already registered",
  "status": 409,
  "code": "DUPLICATE_EMAIL",               # machine-readable, stable
  "detail": "The email 'alice@test.dev' is already in use.",
  "instance": "/users/register",
  "errors": [
    { "field": "email", "code": "DUPLICATE", "message": "Already in use" }
  ],
  "requestId": "req_abc123"                # correlation ID
}

How to test for it: Every 4xx / 5xx response validates against a shared error schema. Error codes are SCREAMING_SNAKE_CASE, stable across versions. requestId (correlation ID) is present on every error for debugging. Localized 'detail' never varies the 'code'.

5. Hypermedia — links over hardcoded URLs

HATEOAS adds overhead; plain REST is simpler. Pick based on client coupling. Hypermedia's real win is decoupling — if your client builds URLs from templates, you've already lost half the benefit.

Bad

# Client hardcodes URL construction
GET /api/v1/orders/42
-> { "id": 42, "items": [...] }
client: fetch('/api/v1/orders/' + orderId + '/refunds')   # deeply coupled

# Breaking change: moving refunds to /refunds?orderId= breaks every client

Good

# Hypermedia — client follows links, never constructs URLs
GET /api/v1/orders/42
-> {
  "id": 42,
  "items": [...],
  "status": "shipped",
  "_links": {
    "self":    { "href": "/api/v1/orders/42" },
    "items":   { "href": "/api/v1/orders/42/items" },
    "refund":  { "href": "/api/v1/orders/42/refunds", "method": "POST" },
    "cancel":  { "href": "/api/v1/orders/42/cancellations", "method": "POST" }
  }
}

# Client:
const refundLink = order._links.refund;
if (refundLink) fetch(refundLink.href, { method: refundLink.method });

# Server can move URL structure without breaking client.
# Actions only appear when available (no refund link on cancelled orders).

How to test for it: If HATEOAS: every resource has _links.self. State-dependent actions appear/disappear based on state (a delivered order has a refund link; a pending order does not). Clients operate without ANY hardcoded URL beyond the entry point. If NOT HATEOAS: document every URL explicitly in OpenAPI — no client surprise.

Contract-first vs code-first — end-to-end comparison

One choice ripples through every phase. Pick deliberately; most teams that chose “code-first, spec will catch up” regret it by month six.

Phase	Contract-first	Code-first
1. Design phase	Write OpenAPI spec first, review with all consumers. All parties agree on contract before code.	Developer picks URL + shape ad-hoc. Spec is generated from annotations later (if at all).
2. Parallel work	Frontend mocks from spec (Prism, MSW). Backend implements from spec. Both start day 1.	Frontend waits for backend to ship. Integration delays accumulate.
3. Breaking changes	Spec diff tool (openapi-diff) runs in CI, blocks breaking changes without major bump.	Breaks detected in staging or production. By then, client code is shipped.
4. Documentation	Spec IS the docs. Always accurate by construction. Swagger UI generated automatically.	Docs drift from reality. Updates forgotten. Swagger annotations rot silently.
5. Testing	Contract tests (Schemathesis) validate server against spec. Failures = real regressions.	Tests validate behaviour you coded, not contract you promised. Drift is invisible.

The one case for code-first: exploratory internal tools that you'll throw away. For anything consumer-facing or cross-team, contract-first pays back its cost within the first month.

← Back to all Labs

Test what you designed, not what you accidentally shipped

Sister lab: the /contract lab teaches tools to VERIFY contracts (Pact, Schemathesis, openapi-diff). This lab teaches how to DESIGN the contracts worth verifying. Design first, then test.

POST /users GET /users/:id PATCH /users/:id { "status": "deactivated" } POST /users/:id/password-resets PATCH /orders/:id { "status": "shipped" } # Nested relationships: POST /users/:userId/orders # Actions as sub-resources: POST /orders/:id/refunds

# Path versioning (common, cache-friendly) GET /api/v1/users GET /api/v2/users # breaking change → new major # OR header versioning (one scheme throughout) GET /api/users Accept: application/vnd.example.v1+json GET /api/users Accept: application/vnd.example.v2+json # Deprecation signal (RFC 8594) GET /api/v1/users Deprecation: true Sunset: Sat, 31 Dec 2026 23:59:59 GMT Link: </api/v2/users>; rel="successor-version"

# v1 → v2 breaking changes without version bump v1: { "id": 1, "name": "Alice" } v2: { "id": "u_1", "fullName": "Alice" } # id type changed, rename # "Small change" that silently breaks clients Renamed `email` → `emailAddress` in response — clients reading `email` see undefined Removed `isActive` field — logic branching on it now hits null Tightened validation: `password` now min 12 chars (was 8) — existing valid users blocked

# Additive-only in a minor release v1.0: { "id": 1, "name": "Alice", "email": "a@b.c" } v1.1: { "id": 1, "name": "Alice", "email": "a@b.c", "phone": "+1..." } // new optional field # Major bump for any breaking change v2.0: { "id": "u_1", "name": "Alice", "email": "a@b.c" } -> documented migration guide + deprecation of v1 for 6 months # "Add new, deprecate old" — coexistence for transition v1.2: { "email": "a@b.c", "emailAddress": "a@b.c" } # both present v1.3: `email` marked deprecated in OpenAPI, both still present v2.0: only `emailAddress` (6 months after v1.3 ships)

# Different shape per endpoint = client cannot branch reliably 400: { "error": "Invalid email" } 400: { "errors": ["email is bad"] } 400: { "message": "Something went wrong", "status": 400 } 400: "Validation failed" # Message-as-API — translating it breaks the client if (err.message === "Email already exists") { ... } // i18n breaks this

# Stable envelope on every 4xx / 5xx HTTP/1.1 409 Conflict Content-Type: application/problem+json # RFC 7807 { "type": "https://api.example.com/errors/duplicate-email", "title": "Email already registered", "status": 409, "code": "DUPLICATE_EMAIL", # machine-readable, stable "detail": "The email 'alice@test.dev' is already in use.", "instance": "/users/register", "errors": [ { "field": "email", "code": "DUPLICATE", "message": "Already in use" } ], "requestId": "req_abc123" # correlation ID }

# Client hardcodes URL construction GET /api/v1/orders/42 -> { "id": 42, "items": [...] } client: fetch('/api/v1/orders/' + orderId + '/refunds') # deeply coupled # Breaking change: moving refunds to /refunds?orderId= breaks every client

# Hypermedia — client follows links, never constructs URLs GET /api/v1/orders/42 -> { "id": 42, "items": [...], "status": "shipped", "_links": { "self": { "href": "/api/v1/orders/42" }, "items": { "href": "/api/v1/orders/42/items" }, "refund": { "href": "/api/v1/orders/42/refunds", "method": "POST" }, "cancel": { "href": "/api/v1/orders/42/cancellations", "method": "POST" } } } # Client: const refundLink = order._links.refund; if (refundLink) fetch(refundLink.href, { method: refundLink.method }); # Server can move URL structure without breaking client. # Actions only appear when available (no refund link on cancelled orders).

Contract-first vs code-first — end-to-end comparison

One choice ripples through every phase. Pick deliberately; most teams that chose “code-first, spec will catch up” regret it by month six.

Phase	Contract-first	Code-first
1. Design phase	Write OpenAPI spec first, review with all consumers. All parties agree on contract before code.	Developer picks URL + shape ad-hoc. Spec is generated from annotations later (if at all).
2. Parallel work	Frontend mocks from spec (Prism, MSW). Backend implements from spec. Both start day 1.	Frontend waits for backend to ship. Integration delays accumulate.
3. Breaking changes	Spec diff tool (openapi-diff) runs in CI, blocks breaking changes without major bump.	Breaks detected in staging or production. By then, client code is shipped.
4. Documentation	Spec IS the docs. Always accurate by construction. Swagger UI generated automatically.	Docs drift from reality. Updates forgotten. Swagger annotations rot silently.
5. Testing	Contract tests (Schemathesis) validate server against spec. Failures = real regressions.	Tests validate behaviour you coded, not contract you promised. Drift is invisible.

The one case for code-first: exploratory internal tools that you'll throw away. For anything consumer-facing or cross-team, contract-first pays back its cost within the first month.