API Design

If you are new here: An API (Application Programming Interface) is how one program asks another for data or work over the network. Your mobile app or website is usually the client; the server (or service) answers with HTTP responses. The contract is everything both sides rely on: paths, JSON shapes, status codes, and error formats. API design is the discipline of making that contract clear and stable so updates do not accidentally break every installed app.

The Problem

It's 2 AM. Crash reports spike because someone renamed a JSON field from user_id to userId. The server is healthy, but old app builds still expect user_id. That is a contract failure: the server changed the rules without a version or migration path clients could follow.

In plain terms: API design is how you keep clients and servers agreeing on paths, payloads, errors, and evolution — so shipping does not silently brick apps in the wild.

That is the problem this lesson exists to solve: predictable contracts instead of “it works if everyone deploys at once.”

Everything below is how to avoid that class of failure.

Resources as nouns

Model your world as resources—things you can name—not as RPC-style URLs that encode the action in the path.

Predictable URLs help caching, routing, logs, and onboarding: people guess right before reading your code.

Example — same user, two operations:

GET /users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbG…

HTTP/1.1 200 OK
Content-Type: application/json
 
{"id":"42","display_name":"Asha","email":"[email protected]"}

Creating a user hits the collection; the server chooses the new id:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"display_name":"Ben","email":"[email protected]"}

HTTP/1.1 201 Created
Location: /users/43
Content-Type: application/json
 
{"id":"43","display_name":"Ben","email":"[email protected]"}

Verbs mean behavior

HTTP methods (verbs) tell intermediaries and clients what kind of operation this is. The ecosystem assumes:

If GET deletes data or POST only reads, caches and retry logic will lie to you—bugs show up under load, not in demos.

Status codes tell the story

The status code is the first thing automated clients use. Use it honestly.

Never return 200 with only {"error": "..."} in the body—clients and caches will treat it as success.

Example — wrong vs right:

HTTP/1.1 200 OK
Content-Type: application/json
 
{"error": "User not found"}

Better:

HTTP/1.1 404 Not Found
Content-Type: application/json
 
{"error":{"code":"USER_NOT_FOUND","message":"No user for that id.","requestId":"req_9c1"}}

Errors machines can parse

Structured errors include a stable machine code, a message for humans, optional field for validation, and a requestId that matches your logs and traces.

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user exists for that id.",
    "requestId": "req_8f3a2b"
  }
}

Example — validation with a field pointer:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email format is invalid.",
    "field": "email",
    "requestId": "req_3d7f91"
  }
}

Versioning signals intent

Breaking changes—removing fields, changing types, renaming keys—must be obvious in your API surface. Silent breaks strand mobile users until they update the app.

See the API Versioning lesson for deprecation timelines and additive patterns. Rule of thumb: old clients keep working until they explicitly move.

Example — same resource, two major versions:

Or one URL with a header:

GET /users/42 HTTP/1.1
Host: api.example.com
API-Version: 2025-01-01

OpenAPI as the written contract

OpenAPI describes endpoints, parameters, bodies, and responses in machine-readable YAML/JSON. Teams use it for docs, code generation, contract tests, and breaking-change detection in CI.

The spec is not bureaucracy—it is how multiple teams ship without breaking each other.

Example — tiny OpenAPI fragment (YAML):

paths:
  /users/{id}:
    get:
      summary: Get one user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Not found

Your real file grows to list every path your API exposes; CI can diff two versions and flag removed fields.

Trade-offs

Why this matters for you

Design as if you do not control every client. Field renames are cheap in git; they are expensive in production. Next lesson: REST APIs—pagination, caching, and idempotency in practice.