Resource Naming
Use plural nouns: /users, /orders, /products. Use HTTP methods for actions: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove). Nest resources for relationships: /users/123/orders. Avoid verbs in URLs — /getUsers is wrong; GET /users is right. Use kebab-case for multi-word resources: /order-items. Keep URLs predictable — a developer should guess endpoints without reading docs.
Response Format
Consistent JSON structure across all endpoints. Success: {data: [...], meta: {total: 100, page: 1}}. Errors: {error: {code: "VALIDATION_ERROR", message: "Email is required", details: [{field: "email", message: "Required"}]}}. Always return appropriate HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error), 429 (Rate Limited), 500 (Server Error).
Pagination & Filtering
Cursor-based (recommended): /users?cursor=abc123&limit=20. Returns a next_cursor for the following page. Handles insertions/deletions without skipping items. Offset-based: /users?page=3&per_page=20. Simple but breaks at scale — page 10000 requires scanning 200,000 rows. Filtering: /products?category=electronics&min_price=100&sort=price:asc. Support common operators and always set reasonable defaults for limit (20-50).
API Versioning
URL versioning: /v1/users, /v2/users. Simplest approach, clear in documentation. Header versioning: Accept: application/vnd.api.v2+json. Cleaner URLs but harder to test in browser. Best practice: Start with v1 from day one. Support at least 2 versions simultaneously. Deprecate with 6+ months notice. Never break existing clients — additive changes (new fields) are safe; removing or renaming fields is not.
Authentication & Security
Use JWT or OAuth 2.0 for API authentication. Include tokens in Authorization header: Bearer eyJ.... Implement rate limiting per API key — see our rate limiting guide. Use HTTPS everywhere. Validate all input with strict schemas (Zod, Joi). Never expose internal IDs or error stack traces. Implement CORS properly for browser clients. Log all API access for auditing.
Documentation
Use OpenAPI 3.0 (Swagger) for machine-readable API specs. Include: endpoint descriptions, request/response examples, authentication details, error codes, and rate limits. Tools: Swagger UI for interactive docs, Redoc for beautiful static docs, Stoplight for design-first workflow. Keep docs in sync with code — generate from annotations or use contract-first development where the spec drives implementation.
Performance Considerations
Support partial responses: /users?fields=id,name,email. Use ETags for caching — return 304 Not Modified when data hasn't changed. Implement gzip compression. Consider GraphQL for clients that need flexible queries. Use batch endpoints for reducing round trips: POST /batch with multiple operations. Monitor p95 latency, not just averages — the tail matters most for user experience.