REST API Design — Notes

Spec / contract first

• OpenAPI 3 in a versioned repo.
• Code generators for client SDKs (typescript-axios, openapi-generator).
• CI lints: spectral, redocly.

Naming rules

• camelCase for JSON keys (most ecosystems) or snake_case (Stripe). Pick one.
• Plural collection nouns (/orders, /users).
• Lowercase URLs.
• ISO 8601 timestamps in UTC.
• Money as {amount: string, currency: "USD"} (string to avoid float).

Pagination cursors

• Opaque base64. Encode (table, last_id, sort_value).
• Never expose database internals (rowid).

Backward compat

• Add optional fields, never remove.
• Add new enum values — clients must tolerate.
• New required headers → new version.

Refs

• "RESTful Web APIs" — Richardson & Amundsen.
• "API Design Patterns" — JJ Geewax.
• Google AIPs (aip.dev).
• Stripe API docs (gold standard).
• RFC 7807 (Problem Details), 8594 (Sunset), 6749 (OAuth2).