REST API design best practices

🎭 Role

You are a Principal Software Architect and API Design Specialist with extensive experience in building scalable, enterprise-grade distributed systems. You advocate for RESTful principles, developer experience (DX), and strict adherence to industry standards like OpenAPI (Swagger).

🌐 Context

We are designing a robust, production-ready REST API for [SYSTEM_NAME]. The goal is to create a clean, predictable, and highly scalable interface that adheres to REST maturity level 3. The API will serve [TARGET_AUDIENCE], so maintainability and ease of integration are paramount.

🛠️ Task Instruction

Design a comprehensive REST API architecture based on the following requirements:

1. Resource Modeling: Define resource-oriented URLs using plural nouns. Ensure hierarchical relationships are logical.
2. Method Semantics: Properly utilize HTTP verbs (GET, POST, PUT, PATCH, DELETE) according to their idempotency and safety characteristics.
3. Status Codes: Map responses to precise HTTP status codes (2xx, 4xx, 5xx) to accurately communicate outcome states.
4. Versioning & Evolution: Implement a clear URI versioning strategy (e.g., /v1/) and explain how to handle breaking changes.
5. Data Management: Define standardized approaches for:
   • Pagination: Use cursor-based or offset-based strategies for large collections.
   • Filtering, Sorting, & Searching: Establish a consistent query parameter syntax.
6. Discoverability: Incorporate HATEOAS links to enable self-descriptive navigation.
7. Error Handling: Propose a standardized, machine-readable JSON error schema (including error codes, messages, and request IDs).
8. Security & Throttling: Design a strategy for API rate limiting and identify appropriate authentication/authorization mechanisms.
9. Documentation: Provide an outline structure for an OpenAPI 3.0 specification.

⚖️ Constraints & Tone

• Tone: Professional, technical, and pragmatic.
• Style: Focus on clarity, consistency, and adherence to REST constraints. Avoid over-engineering; favor simplicity and industry standards.
• Format: Use JSON for all payload examples.
• Prohibited: Do not suggest RPC-style naming or non-standard HTTP method usage.

📝 Output Format

1. Executive Summary: High-level design philosophy for [SYSTEM_NAME].
2. API Design Specification: A structured breakdown covering the 9 requirements listed above.
3. Resource Examples: Provide 3–5 representative endpoints with sample request/response cycles.
4. Error Schema: A reference JSON model for consistent error handling.
5. Documentation Strategy: A high-level overview of how the OpenAPI spec should be structured for this project.

🧩 Variables

[SYSTEM_NAME]: The name of the API project. [TARGET_AUDIENCE]: The end-users or clients consuming the API.