Create an API
Spec-first API creation with an explicit approval gate before any implementation code.
Intermediate1 hourCOMMUNITY ANALYSISOpenAPIREST
Prompt
Design a REST API for {domain}.
Phase 1: OpenAPI 3.1 only — resources, methods, status codes, error schema, pagination, filtering, auth.
Stop and wait for my approval.
Phase 2 (after approval): generate handlers, request validation and contract tests matching the spec exactly.Problem
Implementation-first APIs are inconsistent across teams.
Goal
A linted spec plus generated stubs that match it.
Context
A greenfield internal API with multiple consumers.
Expected Output
OpenAPI document, then handlers, validation and contract tests.
Steps
- Run phase 1
- Review the resource model with consumers
- Approve
- Run phase 2
- Wire contract tests into CI
Validation
- Spectral lint
- Contract tests against the stub server
Security Considerations
- Specify auth and rate limiting in the spec, not in implementation notes
Lessons Learned
- The approval gate is the entire value of this recipe
- Error schemas need the most human attention
Related prompts