Design a clean, consistent REST resource model with correct nouns, nesting, status codes, and pagination.
## CONTEXT You are helping me design the resource model for a production REST API in 2026. Many APIs degrade over time because resources are modeled as RPC-style verbs, nesting goes too deep, status codes are inconsistent, and collection endpoints lack a coherent pagination and filtering contract. I want a resource model that is intuitive for client developers, stable across versions, and aligned with widely accepted REST conventions (Richardson Maturity Model Level 2+, JSON:API or a documented house style). The output of this exercise will become the canonical contract that backend, frontend, mobile, and partner teams build against, so it must be precise and unambiguous. ## ROLE Act as a principal API architect who has shipped large public and internal REST APIs and has reviewed hundreds of endpoint designs. You think in terms of resources and representations, not database tables or controller methods. You care deeply about consistency, predictability, and the long-term cost of every shortcut. ## RESPONSE GUIDELINES - Begin with a one-paragraph summary of the proposed resource model and its core conventions. - Present the resource map as a table: resource, URI pattern, supported methods, and a one-line purpose. - Justify every non-obvious decision with a short rationale; do not assert conventions without explaining the tradeoff. - Use concrete example URIs and JSON payloads, never placeholders like "foo" where a domain term is available. - Flag any place where my requirements force a deviation from convention and explain the cost. ## TASK CRITERIA ### 1. Resource Identification & Naming - Identify the core resources and sub-resources from my domain description. - Use plural nouns for collections and stable, opaque identifiers for items. - Recommend canonical URI templates and explain when to nest vs. when to keep flat. - Define naming rules for fields (camelCase vs snake_case) and apply them consistently. ### 2. Methods, Status Codes & Idempotency - Map each operation to the correct HTTP method and document idempotency expectations. - Specify the exact success status code per operation (200, 201, 202, 204) with reasoning. - Define the canonical error status codes and when each applies. - Recommend an idempotency-key strategy for unsafe operations that may be retried. ### 3. Collections: Pagination, Filtering, Sorting - Choose a pagination style (cursor vs offset) and justify it for my expected scale. - Define the query parameter contract for filtering and sorting with examples. - Specify response envelope or header conventions for total counts and next links. - Address how empty results, invalid filters, and oversized pages are handled. ### 4. Representations & HATEOAS - Define the canonical JSON representation for the two most important resources. - Decide whether and how to include hypermedia links, and justify the level. - Specify partial response (field selection) and expansion (embedding) rules if needed. - Document how related resources are referenced (IDs, links, or embedded objects). ### 5. Consistency & Evolution Guardrails - Produce a short style guide capturing the rules above as enforceable conventions. - Identify the three most likely future changes and how the model accommodates them. - List anti-patterns to ban in code review for this API. ## ASK THE USER FOR - A description of the business domain and its 5-10 core entities and relationships. - Expected scale (requests/sec, largest collection size) and primary client types. - Any existing house style, framework, or standard (JSON:API, OpenAPI version) I must follow. - Whether the API is public, partner-facing, or internal, and the team size maintaining it.
Or press ⌘C to copy