Documentation and Developer Experience

The technical specification of your API is necessary but never sufficient. What developers remember — and what determines whether they recommend your API — is everything around it: how fast they got to a working call, how clear the errors were, how good the examples felt.

Source of Truth: a Machine-Readable Schema

Write the schema first; generate everything else.

• REST — OpenAPI 3.x (Swagger) describes paths, parameters, responses, schemas.
• GraphQL — the SDL schema is itself the contract.
• gRPC — Protobuf .proto files.

From one source you can generate: reference docs, client SDKs in many languages, mock servers, contract tests, validation middleware.

OpenAPI snippet

openapi: 3.0.3
info:
  title: Orders API
  version: "1.0"
paths:
  /orders/{id}:
    get:
      summary: Get an order
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404": { description: Not found }
components:
  schemas:
    Order:
      type: object
      properties:
        id: { type: string, example: "ord_100" }
        status: { type: string, enum: [open, paid, cancelled] }
        amount: { type: integer, example: 4999 }

Examples Beat Reference Docs

Most developers learn by copying a working snippet. Make sure they have one for every endpoint, in multiple languages:

curl https://api.example.com/v1/orders \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD"}'

const order = await client.orders.create({
  amount: 1000,
  currency: 'USD',
});

Show real-looking values, not foo and bar. Show success and at least one error. Show pagination. Show idempotency.

Error Messages That Help

Bad: {"error": "validation failed"}.

Good:

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive integer in cents",
    "field": "amount",
    "doc_url": "https://docs.example.com/errors/validation_error",
    "request_id": "req_abc123"
  }
}

• type — machine-readable.
• message — human-readable, specific.
• field — where the problem is.
• doc_url — link to docs about that error.
• request_id — what to give support.

Time-to-First-Call

The most important DX metric: how long from signup to "I called the API and got a 200." Optimise for it.

• One-page quickstart with a copy-pasteable curl example.
• Test API key visible immediately on dashboard.
• Sandbox or test mode that does not require real billing.
• Live "try it" widget on the docs page.

If a developer can't get a 200 in 5 minutes, you are losing them.

Official SDKs

Most production integrations use SDKs, not raw HTTP. A good SDK:

• Handles auth, retries with backoff, and pagination automatically.
• Types every response (TypeScript / Python type hints / Go structs).
• Surfaces deprecation warnings.
• Is generated from the schema — kept in sync without human effort.

Tools: OpenAPI Generator, Speakeasy, Stainless, Fern, Kiota. Maintaining SDKs by hand in five languages is a tax most teams cannot afford long-term.

Changelog

Every change, every release, dated. Mark deprecations clearly. Link to migration docs. Subscribe-able via RSS or email.

2025-09-15  Added `order.metadata` field (additive).
2025-08-30  Deprecated `order.total`. Use `order.total_cents`. Sunset 2026-03-01.
2025-08-01  v1 generally available.

Status Page

Public, honest, fast to update. When something is broken, customers want to confirm it is not their fault before they file a ticket.

Webhooks Need Their Own DX

• Document every event type and its payload.
• Provide test/replay tools.
• Include signatures and instructions to verify them.
• Document retry policy.

The Small Things That Add Up

• Use stable, prefixed IDs in examples — ord_100 not 123.
• Keep error responses well under 1KB.
• Return Location on 201s; clients shouldn't need to construct URLs.
• Provide pagination headers on lists; don't make clients guess.
• Include request_id on every response, not just errors.
• Honour Idempotency-Key on every mutation.

Internal APIs Deserve DX Too

Internal teams are also developers, also frustrated by bad APIs. Apply the same standards. The cost is low; the productivity gain across the org is large.

Cert Mapping

Closing

You now have a complete API design toolkit: HTTP fundamentals, REST modelling, GraphQL, auth, rate limits, caching, versioning, and developer experience. Pair this with the system design course for the surrounding architecture and the security course for harder threat modelling. The conventions here are how serious products treat their public surface — and how you should treat yours.