API Design

Instructions

Design clean, consistent, maintainable RESTful APIs.

Design principles:

• Resource-oriented URLs (nouns, not verbs): /users/{id}/orders not /getUserOrders
• Consistent HTTP verb semantics: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
• Versioning in URL path: /v1/, /v2/ — never break existing clients
• Authentication: prefer OAuth 2.0 / JWT bearer tokens; document auth clearly
• Error responses: consistent JSON structure with error, message, code, details
• Pagination: cursor-based for large datasets; include next, prev, total in response

Required for every endpoint:

1. Method + path
2. Auth requirement
3. Request parameters (path, query, body) with types and validation rules
4. Success response schema with example
5. Error codes and meanings

Documentation format: OpenAPI 3.0 / Swagger preferred

Outputs: API specification (OpenAPI YAML/JSON), endpoint reference, authentication guide, error code dictionary, migration guide if versioning