STAND WITH UKRAINE
coding

REST API Design Prompt

Good API design is about consistency and predictability. This prompt enforces REST conventions (plural nouns, proper HTTP methods, meaningful status codes) and produces a structured endpoint specification that can be turned into an OpenAPI document. The pagination and versioning sections prevent common architectural mistakes that are expensive to fix after launch.

Prompt Template
You are a senior software architect specialising in RESTful API design.

Design a REST API for the following use case:

Domain: {{domain}}
Resource(s): {{resources}}
Operations needed: {{operations}}
Authentication method: {{auth_method}}
API consumers: {{consumers}}

For each endpoint, provide:
- HTTP method and path (following REST conventions)
- Request body schema (JSON)
- Response schema with status codes (200, 201, 400, 401, 403, 404, 422, 500)
- Brief description of the operation

Design principles to follow:
- Use nouns for resource paths, not verbs
- Use plural nouns for collections (/users not /user)
- Nest resources only up to 2 levels deep
- Use query parameters for filtering, sorting, and pagination
- {{additional_requirements}}

After the endpoint list, provide:
1. A minimal OpenAPI 3.0 YAML snippet for the most important endpoint
2. Pagination strategy recommendation
3. Versioning strategy recommendation

Variables

{{domain}}The business domain, e.g., "e-commerce", "project management", "healthcare"
{{resources}}The main data entities, e.g., "users, products, orders"
{{operations}}What the API needs to do, e.g., "CRUD for products, order placement, user registration"
{{auth_method}}Authentication approach, e.g., "JWT Bearer token", "API key", "OAuth2"
{{consumers}}Who calls the API, e.g., "mobile app", "third-party integrations", "internal microservices"
{{additional_requirements}}Extra constraints, or "None"

Example

Input
domain: task management
resources: projects, tasks, users
operations: CRUD for projects and tasks, task assignment, status updates
auth_method: JWT Bearer token
consumers: web app, mobile app
additional_requirements: Support bulk task creation
Output
GET    /projects              — list all projects (paginated)
POST   /projects              — create a project
GET    /projects/{id}         — get a project
PATCH  /projects/{id}         — update a project
DELETE /projects/{id}         — delete a project
GET    /projects/{id}/tasks   — list tasks for a project
POST   /projects/{id}/tasks   — create a task
POST   /projects/{id}/tasks/bulk — bulk create tasks
GET    /tasks/{id}            — get a task
PATCH  /tasks/{id}            — update a task (status, assignee)
DELETE /tasks/{id}            — delete a task

Related Tools

AI Prompt BuilderAI JSON Schema BuilderAI Token Counter

FAQ

Should I use PUT or PATCH for updates?
Use PATCH for partial updates (most common) and PUT for full replacement. PATCH is preferred for typical REST APIs because clients only need to send changed fields, reducing payload size and avoiding accidental data loss.
How do I handle relationships between resources?
Nest related resources up to two levels (e.g., /projects/{id}/tasks) for strong ownership relationships. For loose associations, use a query parameter (e.g., GET /tasks?assignee_id=123) to avoid deeply nested paths.
What pagination strategy should I use?
Use cursor-based pagination for large, frequently updated datasets (avoids the "page drift" problem). Use offset/limit pagination for smaller, stable datasets where the total count is needed. Add Link headers per RFC 5988.

Related Prompts

Code Review Prompt

This prompt structures code reviews into five clear categories so the AI produces actionab...

Code Documentation Prompt

Auto-generated documentation is only useful when it goes beyond repeating the function sig...

Database Schema Design Prompt

Database schema mistakes are the most expensive to fix after launch because they require d...