Designing and scaffolding an API
Go from a rough requirement to an OpenAPI contract, generated handlers, validation and contract tests.
IntermediateCOMMUNITY ANALYSISOpenAPIRESTTypeScriptJava
Prompt
Design a REST API for {domain}. Produce an OpenAPI 3.1 specification first: resources, methods, status codes, error schema, pagination and auth. Wait for my approval before generating any implementation code.Problem
APIs get implemented before they are designed, and the contract is reverse-engineered from handlers later.
Scenario
A new internal API with three consuming teams.
Architecture
- Spec-first
- Generated server stubs
- Contract tests in CI
Why Bob?
Spec-first work benefits from fast iteration on structure before anyone writes handlers.
Prompt
Substitute {domain}, and hold the line on spec-before-code.Bob Workflow
- Draft the resource model
- Produce OpenAPI
- Generate handlers and validation after approval
Generated Result
A lintable OpenAPI document plus stubs and a consistent error schema.
Validation
- Spectral lint
- Contract tests against the stub server
Security
Define authentication and rate-limit expectations in the spec; do not leave them to implementation.
Lessons Learned
- The approval gate between spec and code is the whole trick
- Error schemas are where generated APIs are weakest
Resources
- OpenAPI 3.1 specification