API Design taste — ChatGPT prompt: what it does, how to install
Opinionated REST API design rules with confidence scores. It guides AI models on clean routing, error contracts, and schema validation.
Open on GitHubWhat API Design taste does
This prompt sets seventeen engineering standards for REST architecture. Every directive carries an explicit confidence metric ranging between 0.75 and 0.95. The guidelines mandate resource-based endpoints with plural nouns like /users or /orders instead of RPC action verbs. Versioning belongs directly inside the path segment (/v1/...).
Payload validation requires strict schemas using Zod, OpenAPI, or JSON Schema, rejecting any undocumented attributes. For large collections, cursor-based pagination replaces offset indexing, packaging metadata into an envelope containing data and nextCursor. Critical write operations involving payments or orders must supply idempotency keys.
Mixing camelCase and snake_case in the same API is explicitly prohibited. The prompt rejects manual SDK authoring in favor of OpenAPI 3 generation. Sensitive data and tokens must stay out of query strings, remaining strictly inside request headers or bodies.
What it helps with
- structure REST routes using plural nouns instead of RPC verbs
- standardize error payloads with
code,message, anddetails - set up cursor-based pagination with a stable response envelope
- enforce request body validation and reject unmapped fields
Example prompts for the agent
- Review my
/ordersroute definitions against the REST design guidelines - Design an error response envelope with standard HTTP status codes
- Draft an OpenAPI 3 specification for cursor-paginated endpoints
How to install API Design taste
How to use
Paste the text at the start of a chat or into project instructions
Manually: put the files in place
.claude/commands/prompts.csv.mdQuestions about API Design taste
How to install API Design taste in Claude Code?
Place the file into .claude/commands/prompts.csv.md within your project.
What does API Design taste do?
It instructs the model to enforce strict REST conventions, including camelCase JSON fields, cursor pagination, and standard HTTP codes.
How does the prompt handle request validation?
Every incoming body must pass schema validation via Zod, OpenAPI, or JSON Schema while rejecting any unlisted fields.
Source text
prompts.csv · CC0-1.0
# API Design taste - Prefer resource-oriented URLs with nouns and HTTP verbs for actions, not RPC-style verbs in the path. Confidence: 0.95 - Version APIs in the URL path (`/v1/...`) and keep breaking changes out of an existing major version. Confidence: 0.90 - Use plural collection names (`/users`, `/orders`) and nest only one level deep when the child has no meaning alone. Confidence: 0.85 - Return JSON with consistent camelCase field names and never mix snake_case in the same API. Confidence: 0.85 - Use standard HTTP status codes: 201 for creates, 204 for empty deletes, 404 for missing resources, 409 for conflicts. Confidence: 0.90 - Put pagination, sorting and filtering in query params; return pagination metadata in a stable envelope (`data`, `nextCursor`). Confidence: 0.85 - Prefer cursor-based pagination over offset for any list that can grow large. Confidence: 0.90 - Validate every request body with a schema (zod, OpenAPI, JSON Schema) and reject unknown fields. Confidence: 0.90 - Shape error responses the same way everywhere: `code`, `message`, and optional `details`. Confidence: 0.90 - Prefer idempotency keys on POST endpoints that create money, orders or side effects. Confidence: 0.85 - Use ETags or `If-Match` for concurrent updates on contested resources. Confidence: 0.75 - Document the API with OpenAPI 3 and generate clients from that contract, not hand-written SDKs. Confidence: 0.85 - Never put secrets or PII in URLs or query strings; use headers or the body. Confidence: 0.95 - Prefer explicit expansion (`?include=`) over always embedding related entities. Confidence: 0.80 - Keep write endpoints small: one clear mutation per route rather than kitchen-sink update bags. Confidence: 0.80 - Rate-limit by API key or user and return `Retry-After` when limited. Confidence: 0.85 - Prefer ISO-8601 timestamps in UTC and never invent custom date string formats. Confidence: 0.95
© f · CC0-1.0 · f/prompts.chat
