Software Engineer · beginner
API-First Service with OpenAPI, a Generated SDK, and Contract Tests
A REST API designed spec-first — the OpenAPI document is written before the code, the server validates requests against it, a client SDK is generated from it, and contract tests fail the build if the implementation ever drifts from the contract.
Project overview
Design-first APIs with generated clients are how platform and product teams ship, and "the spec is the source of truth" is a phrase you will hear in every backend interview. Contract tests show you understand integration risk, which is what separates a junior who writes endpoints from one who ships them safely.
Real-world use case
A mobile team and a backend team work in parallel. The mobile team builds against the generated SDK from day one, and when the backend changes a field, CI catches it before anyone’s app breaks.
Tools and technologies
- OpenAPI 3.1
- FastAPI or Express
- OpenAPI Generator
- Schemathesis
- GitHub Actions
- Docker
Skills you can demonstrate
API Design, Contract-First Development, SDK Generation, Contract and Property-Based Testing, CI Automation
Build roadmap
- Write the spec first
Before any code, write the OpenAPI document for two resources with full schemas, examples, and error responses. Lint it. Review it with the AI prompt. - Mock it
Run a mock server from the spec and hit it with curl. This is what a front-end teammate would build against while you implement. - Implement the server
Build the endpoints with request and response validation wired to the spec. Every mismatch should be a 400 or a failing test, never a silent pass. - Generate the SDK
Generate a TypeScript client from the spec, write a ten-line script that uses it end to end, and commit it as its own package. - Add contract tests
Run Schemathesis against the live server in CI. Introduce a deliberate drift and confirm the build goes red with a useful message. - Publish docs and write up
Host interactive docs from the spec, add a README explaining the workflow, and include the drift example as proof that the contract is enforced.
Ways to extend the project
Publish the SDK to a package registry with semantic versioning driven by the spec diff, and host the API docs from the same OpenAPI file.
How to showcase your work
- GitHub: The spec, the server, the generated SDK as a separate package, the contract tests, and hosted docs. A drift example in the README where CI catches a breaking change.
- LinkedIn: Show the diff: change a response field in the server, watch the contract test fail with the exact operation and schema mismatch.
- Resume: Lead with "API-first design with OpenAPI" and "contract testing", then mention SDK generation.