API Development
Design REST API Endpoints for a Feature
Get a clean REST design with resources, status codes, validation, pagination and error shapes - tailored to your language and framework.
The Prompt
design-rest-api-endpoints.md
You are an API designer who values consistency and boring, predictable interfaces. Language: {{language}} Framework: {{framework}} Feature: {{feature}} Existing conventions in our API: {{conventions}} Auth model: {{auth}} Expected scale and read/write ratio: {{scale}} Deliver: 1. Resource model: entities, relationships, identifiers 2. Endpoint table: method, path, purpose, auth requirement, success status, main error statuses 3. Request and response JSON examples for each endpoint, including a consistent error shape 4. Validation rules per field (use {{framework}} idioms where they exist - e.g. Zod, Pydantic, Bean Validation) 5. Pagination, filtering and sorting approach with example query strings 6. Idempotency and concurrency handling for writes 7. Versioning and deprecation plan 8. A short {{framework}} sketch for one write endpoint (route/controller signature + where validation and auth hook in) - not a full app 9. Three design decisions you would revisit if scale increased 100x Follow my existing conventions where I stated them, even if you would choose differently. Keep code samples idiomatic for {{language}} + {{framework}}.
Negative prompt
Included when you copy the prompt
Do not ignore the stated conventions in favour of your preferred style. Do not invent GraphQL, RPC, or event-driven designs unless asked. Do not switch to a different language or framework than {{language}} + {{framework}}. Do not omit auth requirements, error shapes, or status codes. Do not propose breaking URL schemes that conflict with {{conventions}}. Do not hand-wave pagination ("just use page") without query parameter examples. Do not dump a full project scaffold - one endpoint sketch is enough. Do not promise unbounded scale without noting what would need to change.
Fill in your details below - this prompt updates as you type, then copy it.
Fill in your details
0 of 6 filled. Preview updates as you type - then copy the finished prompt (negative prompt included when present).
design-rest-api-endpoints.md
Prompt preview
You are an API designer who values consistency and boring, predictable interfaces. Language: {{language}} Framework: {{framework}} Feature: {{feature}} Existing conventions in our API: {{conventions}} Auth model: {{auth}} Expected scale and read/write ratio: {{scale}} Deliver: 1. Resource model: entities, relationships, identifiers 2. Endpoint table: method, path, purpose, auth requirement, success status, main error statuses 3. Request and response JSON examples for each endpoint, including a consistent error shape 4. Validation rules per field (use {{framework}} idioms where they exist - e.g. Zod, Pydantic, Bean Validation) 5. Pagination, filtering and sorting approach with example query strings 6. Idempotency and concurrency handling for writes 7. Versioning and deprecation plan 8. A short {{framework}} sketch for one write endpoint (route/controller signature + where validation and auth hook in) - not a full app 9. Three design decisions you would revisit if scale increased 100x Follow my existing conventions where I stated them, even if you would choose differently. Keep code samples idiomatic for {{language}} + {{framework}}.
Examples
Example input
Language: TypeScript Framework: NestJS Feature: Customer wishlists - users can create named lists and add product IDs. Conventions: /v1 prefix, snake_case JSON, cursor pagination via ?cursor=&limit=, errors as { "error": { "code", "message", "details" } }, UUIDs for ids. Auth: Bearer JWT; users only access their own lists. Admins have role=admin. Scale: ~50k DAU; reads 20x writes; lists rarely exceed 200 items.
What you should get
1. Resources: Wishlist (id, user_id, name, created_at); WishlistItem (wishlist_id, product_id, added_at). User 1 - N wishlists; wishlist 1 - N items. 2. Endpoints (excerpt): | Method | Path | Auth | Success | | GET | /v1/wishlists | owner | 200 | | POST | /v1/wishlists | owner | 201 | | POST | /v1/wishlists/:id/items | owner | 201 | | DELETE | /v1/wishlists/:id/items/:product_id | owner | 204 | 3. Error example: { "error": { "code": "not_found", "message": "Wishlist not found", "details": {} } } 4. Validation (class-validator / Zod DTO): name 1 - 80 chars; product_id UUID; limit 1 - 100 default 20. 5. Pagination: GET /v1/wishlists?limit=20&cursor=eyJpZCI6Ii4uLiJ9 6. Writes: Idempotency-Key on POST items; unique (wishlist_id, product_id) so retries are safe. 7. Versioning: stay on /v1; additive fields only; deprecate via Sunset header. 8. NestJS sketch: ```ts @Post(':id/items') @UseGuards(JwtAuthGuard) async addItem( @Param('id', ParseUUIDPipe) id: string, @Body() dto: AddWishlistItemDto, @Req() req: RequestWithUser, @Headers('idempotency-key') idempotencyKey?: string, ) { /* ownership check → upsert item */ } ``` 9. At 100x: denormalise item counts, cache list summaries, consider async fan-out for large imports.
How to get a good result
Done when
1. Resources: Wishlist (id, user_id, name, created_at); WishlistItem (wishlist_id, product_id, added_at). User 1 - N wishlists; wishlist 1 - N items. 2. Endpoints (excerpt): | Method | Path | Auth | Success | | GET | /v1/wishlists | owner | 200 | | POST | /v1/wishlists | owner | 201 | | POST | /v1/wishlists/:id/items | owner | 201 | | DELETE | /v1/wishlists/:id/items/:product_id | owner | 204 | 3. Error example: { "error": { "code": "not_found", "message": "Wishlist not found", "details": {} } } 4. Validation (class-validator / Zod DTO): name 1 - 80 chars; product_id UUID; limit 1 - 100 default 20. 5. Pagination: GET /v1/wishlists?limit=20&cursor=eyJpZCI6Ii4uLiJ9 6. Writes: Idempotency-Key on POST items; unique (wishlist_id, product_id) so retries are safe. 7. Versioning: stay on /v1; additive fields only; deprecate via Sunset header. 8. NestJS sketch: ```ts @Post(':id/items') @UseGuards(JwtAuthGuard) async addItem( @Param('id', ParseUUIDPipe) id: string, @Body() dto: AddWishlistItemDto, @Req() req: RequestWithUser, @Headers('idempotency-key') idempotencyKey?: string, ) { /* ownership check → upsert item */ } ``` 9. At 100x: denormalise item counts, cache list summaries, consider async fan-out for large imports.
FAQ
- What do I fill in before I copy this prompt?
- Replace these placeholders with your details: language, framework, feature, conventions, auth, scale. Required fields are marked on the page. The prompt text updates as you type.
- Which AI tools is this prompt written for?
- It works best with ChatGPT, Claude, Cursor. Copy the filled prompt and paste it into the tool you already use.
- What should a good result look like?
- 1. Resources: Wishlist (id, user_id, name, created_at); WishlistItem (wishlist_id, product_id, added_at). User 1 - N wishlists; wishlist 1 - N items. 2. Endpoints (excerpt): | Method | Path | Auth | Success | | GET | /v1/wishlists | owner | 200 | | POST | /v1/wishlists | owner | 201 | | POST | /v1/wishlists/:id/items | owner | 201 | | DELETE | /v1/wishlists/:id/items/:product_id | owner | 204 | 3. Error example: { "error": { "code": "not_found", "message": "Wishlist not found", "details": {…
Best for
- Backend developers
- Tech leads
- Architects
Related Prompts
More prompts like this — same topic and style.
