api-design

API Design

Core Principles

• Contract-First — Define API spec before implementation
• OpenAPI 3.2 — Use OpenAPI for REST API documentation
• URL Versioning — Version in path /v1/, with Sunset headers
• Idempotency — PUT/DELETE must be idempotent, POST uses Idempotency-Key
• Cursor Pagination — Avoid offset-based pagination
• RFC 7807 Errors — Standard Problem Details format
• No backwards compatibility — Delete, don't deprecate

---

Quick Reference

When to Use What

Scenario	Choice	Reason
Public API / MVP	REST	Simple, universal, easy debugging
Frontend-driven / Mobile	GraphQL	Fetch exactly what you need
Microservices internal	gRPC	High performance, strong typing
Real-time data	gRPC / GraphQL Subscriptions	Bidirectional streaming

---

REST API Design

Resource Naming

# Good
GET  /users              # List users
GET  /users/123          # Get user
POST /users              # Create user
PUT  /users/123          # Replace user
PATCH /users/123         # Update user
DELETE /users/123        # Delete user

# Nested resources
GET /users/123/orders    # User's orders

# Actions (when CRUD doesn't fit)
POST /users/123/activate # Action on resource

# Query parameters for filtering
GET /users?status=active&role=admin&limit=20

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Read	Yes	Yes
POST	Create	No	No
PUT	Replace	Yes	No
PATCH	Update	No	No
DELETE	Remove	Yes	No

Status Codes

# Success
200 OK              - Successful GET/PUT/PATCH
201 Created         - Successful POST (include Location header)
204 No Content      - Successful DELETE

# Client Errors
400 Bad Request     - Malformed request syntax
401 Unauthorized    - Missing/invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource doesn't exist
409 Conflict        - Duplicate/conflict (e.g., unique constraint)
422 Unprocessable   - Validation failed
429 Too Many        - Rate limited

# Server Errors
500 Internal Error  - Unexpected server error
503 Unavailable     - Service temporarily down