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.
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+.