REST API Design

Design or review an API against the conventions that matter: resource naming, cursor pagination, RFC 9457 errors, idempotency, and OpenAPI 3.1.

[DESIGN a new API / REVIEW my existing API] for [THE DOMAIN, e.g. "order management for our storefront"].

The resources and operations needed: [WHAT CLIENTS MUST BE ABLE TO DO: plain language list]
Consumers: [INTERNAL SERVICES / THIRD-PARTY DEVELOPERS / MOBILE APPS: third parties raise the stakes on consistency and versioning]
Existing conventions to match: [PASTE A REPRESENTATIVE ENDPOINT OR YOUR STYLE RULES, or "greenfield"]
[IF REVIEWING: paste the current endpoint list / OpenAPI spec]

Apply these standards, flagging every deviation with its cost:
1. **Resources, not verbs**: plural-noun collections (/orders, /orders/{id}), lowercase kebab-case paths, actions expressed via HTTP methods; a custom action endpoint is a last resort, named and justified. Nesting capped at ~2 levels: deeper relationships become top-level collections with filters.
2. **Pagination from v1, cursor-based**: an opaque cursor token (clients never parse it), page_size with a documented max, and a stable sort. Offset pagination only with the trade-off stated (it skips/duplicates under concurrent writes and degrades at depth). Adding pagination later is a breaking change. It goes in now even for "small" collections.
3. **Errors as RFC 9457 Problem Details**: application/problem+json with type, title, status, detail, instance, plus domain extension fields. One error shape everywhere; no ad-hoc {"error": "oops"} variants.
4. **Mutation semantics, precise:** PUT replaces wholly and is idempotent; PATCH is partial (state whether JSON Merge Patch or JSON Patch); POST-that-creates supports an Idempotency-Key header so client retries can't double-charge/double-create. Describe the server behavior (store key + response, replay on repeat).
5. **Versioning strategy, chosen once**: state it (URL /v1/ or media-type evolution), the compatibility promise (what counts as breaking), and the deprecation path (Sunset headers, timeline).
6. **The operational surface:** 429 with Retry-After for rate limits, consistent timestamp format (RFC 3339 UTC), and request IDs echoed for support.

Deliver:
- The endpoint table: method | path | purpose | status codes | notes.
- Representative request/response bodies for the 3 most important endpoints, including one error response and one paginated response.
- The OpenAPI 3.1 skeleton for those endpoints (3.1 semantics, JSON Schema 2020-12 types, no nullable: true).
- **The breaking-change ledger:** every design decision that would be breaking to change later (field names, pagination shape, error format), listed. This is the review's highest-value section, because these are one-way doors.

Rules: boring and consistent beats clever, where two conventions are defensible, pick the one my existing endpoints already use. If my requested operations imply a problematic resource model (verbs that don't map, god-objects), raise it before designing around it.

How to use

These aren't style preferences: they're the convergent rules of the Zalando/Microsoft/Google API guidelines, and the two that hurt most when skipped are pagination-from-day-one and a single error format (both are breaking changes to retrofit). The breaking-change ledger reframes API review around what actually matters: distinguishing decisions you can revise from one-way doors. For public APIs, run the naive-consumer test: hand the endpoint table to someone who wasn't in the room and watch where they guess wrong.

More coding prompts

Write the commit message for this change.

Diff:
"""
[PASTE THE STAGED DIFF]
"""

Why I made this change: [THE REASON, THE TICKET, THE BUG REPORT, or "you infer it"]
Convention: [Conventional Commits / this repo's existing style, pasted below / plain]
Recent commits from this repo, to match style:
"""
[PASTE 5-10 RECENT COMMIT SUBJECT LIN

Commit Message

Write a commit message that explains why the change was made, in Conventional Commits format, split into separate commits when needed.

Codingbeginner

Help me recover from a git mistake without making it worse.

What I was trying to do: [THE GOAL]
What I ran: [THE EXACT COMMANDS, IN ORDER]
What happened instead: [THE OUTPUT OR THE STATE NOW]
Has this been pushed or shared: [YES/NO, and to which branch and whether anyone else has pulled]
Uncommitted work I cannot lose: [WHAT AND WHERE, o

Undo a Git Mistake

Recover from a bad commit, force push, wrong branch, or lost work with a reversible plan and the exact commands, explained before you run them.

Codingintermediate

Handler code, routes, and models:
"""
[PASTE THE ROUTE DEFINITIONS, HANDLERS, REQUEST AND RESPONSE TYPES, VALIDATION SCHEMAS, AND MIDDLEWARE]
"""

Generate an OpenAPI 3.1 specification from the code above.

API name, version, and base URL: [DETAILS]
Auth scheme: [BEARER JWT / API KEY / OAUTH / SESSION COOKIE, and where it is enforced]
Con

OpenAPI Spec From Code

Generate an accurate OpenAPI 3.1 spec from handler code, including error responses and auth, with gaps flagged instead of invented.