API Design Assistant

The Prompt

Design a RESTful API for [DOMAIN/FEATURE]. Follow these principles:

1. **Resources:** Identify nouns (not verbs) as resources
2. **HTTP Methods:** GET (read), POST (create), PUT (full update), PATCH (partial), DELETE
3. **URLs:** Plural nouns, nested for relationships (e.g., /users/{id}/orders)
4. **Status Codes:** Use correct codes (201 Created, 404 Not Found, 422 Unprocessable)
5. **Error Format:** Consistent error response body with code, message, and field-level details
6. **Pagination:** Cursor-based for large collections
7. **Versioning:** URL path prefix (/v1/) or Accept header

For each endpoint, provide:
- Method + URL
- Request body (if applicable)
- Success response (with status code)
- Error responses
- Rate limiting considerations
- Auth requirements

Also flag: N+1 query risks, missing indexes, and pagination edge cases.

How To Use It

Replace [DOMAIN/FEATURE] with your use case (e.g., “e-commerce order management” or “team collaboration workspace”). Provide existing data models if you have them.

Why It Works

API design requires balancing many constraints simultaneously. This prompt encodes industry best practices so the AI produces APIs that feel familiar to developers, handle errors gracefully, and scale predictably.

Variations

GraphQL schema designer:

Design a GraphQL schema for [DOMAIN]. Include: types, queries, mutations, subscriptions, and explain your choices for connections vs simple lists.

API review:

Review this existing API for: inconsistencies in naming, missing error cases, N+1 risks, and breaking change potential. Suggest improvements.

OpenAPI spec generator:

Generate an OpenAPI 3.1 specification for this API design. Include schemas, examples, and security definitions.