Architecture & data · Service
API Design
Contract-first: we agree the specification before anyone writes a handler, so your frontend, your partners and your backend can build in parallel against the same contract.
POST /v1/bookings Authorization: Bearer ‹token› Idempotency-Key: 5f1c9a2e-… 201 Created # same key, retried → same 201, no duplicate 409 Conflict Content-Type: application/problem+json { "title": "Slot taken", "status": 409 }
IllustrationSafe retries with idempotency keys, and machine-readable errors in the RFC 9457 format.
Who is API Design for?
For products that partners, apps and services need to integrate with, without surprises.
Siloed data
Sales, operations and finance each keep their own version of the truth, and the versions disagree.
What do you get?
- An OpenAPI 3.1 specification, reviewed with the teams who will call it
- Authentication and authorization design: OAuth 2.0 / OIDC, API keys, or both
- Written conventions for errors, pagination, versioning and rate limits
- A reference implementation, contract tests and developer docs
How do you know it's done?
- Clients can retry any write safely
- A breaking change fails the build before it reaches a consumer
- A new consumer can integrate from the docs alone
How does an engagement run?
- 01
Brief. A few minutes with our intake. Your context arrives before the call does.
- 02
Intro call. Thirty minutes. We ask the hard questions and tell you honestly whether we're the right fit.
- 03
Written scope. Scope, exclusions, milestones and a fixed price per phase, in writing, before any invoice.
- 04
Architecture. Diagrams and decision records you review and approve before the build starts.
- 05
Build. Working software on staging, demoed on a fixed cadence. You see progress, not status reports.
- 06
Handover. Code, infrastructure, docs and runbooks in your accounts. Ongoing support only if you want it.
How is it priced?
By scope. After the call you get a written scope with exclusions, milestones and a fixed price per phase. Payment follows accepted milestones. The budget range you pick in the brief isn't a quote; it helps us suggest a first phase that fits.
Which technologies do you use?
Our usual stack for API Design. We work with yours when you have one.
- OpenAPI 3.1
- TypeScript
- NestJS
- PostgreSQL
- Redis
- AWS
API Design: questions and answers
What does contract-first API design mean?
The API specification is agreed before anyone writes a handler, so your frontend, your partners and your backend can build in parallel against the same contract.
Which standards do you use?
OpenAPI 3.1 for the specification; OAuth 2.0 / OIDC, API keys or both for authentication; and written conventions for errors, pagination, versioning and rate limits.
How do you prevent breaking changes?
Contract tests run in the build pipeline, so a breaking change fails the build before it reaches a consumer.
Start a brief for API Design.
A few questions, about three minutes. Nothing is sent until you review it and press Send, and the first call is thirty minutes to check fit, both ways.