codingAPI design

REST API Endpoint Designer

Designs RESTful API endpoints with routes, methods, request/response schemas, auth, and error codes.

Prompt

You are a backend architect specialising in API design for [industry] applications. Design the REST API endpoints for a [feature/module] targeting [target users/clients]. The goal is to create a consistent, well-documented API. For each endpoint, format the output as a structured specification with: (1) HTTP method and route path following RESTful conventions, (2) description of what it does, (3) authentication requirement (public/authenticated/admin), (4) request headers, (5) request body schema with TypeScript interface (for POST/PUT/PATCH), (6) query parameters with types and defaults (for GET), (7) success response with status code and example JSON body, (8) error responses: at least 2 error cases with status codes and body format. For example, a 404 response might look like: '{ "error": "NOT_FOUND", "message": "Resource with id [id] does not exist" }'. Also include: a base URL suggestion, API versioning strategy, and pagination approach for list endpoints (cursor vs offset, with justification for your choice). You must ensure all endpoints use consistent naming conventions. Avoid mixing plural and singular resource names. Only expose fields the client actually needs. Tone should be precise and technical.

Why this prompt works

Most API design prompts produce English descriptions that engineers then have to translate into types. This one demands TypeScript interfaces for request bodies, which makes the output paste-ready into a real codebase. The error-response schema requirement (with the worked example showing both code and message) produces consistent error handling across endpoints, which is where most APIs drift apart. The pagination justification is a small detail with outsized impact: requiring the model to choose between cursor and offset and explain why is what produces a coherent API, not a mishmash of conventions. The 'avoid mixing plural and singular resource names' constraint is the single most-broken rule in real APIs and surfacing it explicitly tends to produce cleaner output.

When to reach for it

You're scoping a new feature and need an endpoint design before you start coding the backend.
You're standardising APIs across a team and want a consistent template every endpoint design follows.
You're scoping a frontend integration and want a reference spec to validate against once the backend is delivered.

How to customise it

The 'feature/module' input drives most of the output. Be specific about resources and relationships. 'A subscription system' produces vague output; 'a subscription system where users can have multiple plans, plans have feature flags, and billing is monthly with proration on plan changes' produces specific endpoints with edge cases addressed. For APIs targeting external developers (public APIs), add 'optimise for backwards compatibility' to the brief. For internal-only APIs, you can ask the model to skip the versioning section.

What good output looks like

Per-endpoint blocks with method, route, description, auth requirement, headers, request body schema (TypeScript interface), query params (table), success response (status code, JSON), and at least 2 error responses. The base URL, versioning strategy, and pagination notes appear once at the top. Naming is consistent (always plural for collections, singular for individual resources). Total length scales with endpoint count, typically 5 to 8 endpoints producing a 1,500 to 2,500 word spec.

REST APIAPI designbackendendpointsTypeScriptChatGPT / Claude