API Design Basics

9 examples for HTTP API design - 6 basic and 3 intermediate.

Prerequisites

uv pip install fastapi pydantic python-jose[cryptography] argon2-cffi httpx

• Security patterns here apply across FastAPI, Django, and Flask APIs on Python 3.14.

Basic Examples

1. Resource URLs

Nouns in paths, verbs in HTTP methods.

GET /users
POST /users
GET /users/{id}
PATCH /users/{id}
DELETE /users/{id}

• Plural resource names.
• Avoid RPC-style action URLs for CRUD.
• Nest sub-resources: /users/{id}/orders.

Related: GraphQL in Python - alternative query model

2. Status Codes

Map outcomes to HTTP semantics.

201 Created on POST success
204 No Content on DELETE success
409 Conflict on duplicate resource

• Do not return 200 for errors.
• 422 for validation failures.
• 429 for rate limits.

3. Error Envelope

Stable machine-readable errors.

{"error": {"code": "invalid_email", "message": "Email format invalid", "field": "email"}}

• Include code, message, optional field.
• Log correlation id server-side.
• Never leak stack traces.

Related: Input Validation & Injection - validation errors

4. Versioning

Explicit API versions.

/v1/users
Accept: application/vnd.example.v1+json

• URL prefix is simplest.
• Document deprecation timelines.
• Avoid silent breaking changes.

5. Pagination

Cursor or offset patterns.

?limit=20&cursor=eyJpZCI6MTB9

• Prefer cursors for large tables.
• Include total only when cheap.
• Cap max page size.

6. Idempotency

Safe retries for POST.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

• Store key to result mapping TTL.
• Critical for payments.
• Return same response on replay.

Intermediate Examples

7. Auth Header

Bearer tokens.

Authorization: Bearer <access_token>

• HTTPS only.
• Short-lived access tokens.
• Separate refresh for browsers.

Related: OAuth2 & JWT - flows

8. Rate Limit Headers

Tell clients remaining quota.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
Retry-After: 60

• Return 429 when exceeded.
• Document limits in OpenAPI.
• Stricter limits on auth routes.

Related: Rate Limiting & Abuse Prevention - throttles

9. OpenAPI Contract

Publish schema for clients.

openapi: 3.1.0
paths:
  /health:
    get:
      responses:
        "200":
          description: OK

• Codegen for clients.
• Contract tests in CI.
• Keep examples realistic.

External Related Links

• Official Python Documentation - The definitive source (Tutorial, Library Reference, Language Reference, HOWTOs).
• Python HOWTOs (Official) - Practical topic-focused guides.
• Real Python - In-depth tutorials, courses, and practical guides.
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• Python Crash Course (3rd Edition) - Beginner-friendly projects (Eric Matthes).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.