REST API Design Guide

Use nouns for resources, not verbs. Keep URLs predictable and consistent. Version your API from day one with a /v1/ prefix.

Status Codes

Return the right HTTP status code. 200 for success, 201 for creation, 404 for missing resources, and 422 for validation errors. Never return 200 with an error body.

Pagination

Always paginate list endpoints. Use ?limit= and ?offset= query parameters. Include a total count in the response so clients can build pagination UIs.