Contract
OpenAPI spec
Streaming, jobs, errors, idempotency keys — and a mock server.
API Design for AI Systems
Contracts for non-deterministic backends: streaming, jobs, idempotency, errors a client can handle, and versioning that survives a model swap.
Created by Baljeet Dogra
Course Objectives
- Choose sync, stream or a job because of latency and failure, not fashion.
- Make retries safe. Make model swaps a version, not a breaking surprise.
- Return errors a client can branch on — including “the model abstained”.
- Write an OpenAPI contract a frontend can mock.
What you will produce
Service
Reference API
One AI feature behind that contract, with a changelog for a model swap.
4 weeks curriculum
Expand a part for the syllabus. Content stays searchable when closed.
01 Shapes of an AI call Week 1
Request/response, streaming, long jobs. TTFT vs total time.
- Sync
- SSE / streaming
- Jobs
- Timeouts
02 Safety in the contract Week 2
Idempotency keys, at-least-once clients, what to log and what never to log.
- Idempotency
- PII
- Authz
- Audit
03 Errors and versions Week 3
Typed errors, abstention, deprecations, model IDs as config not path magic.
- Error model
- Abstention
- Versioning
- Compatibility
04 Ship the spec Week 4
OpenAPI, mocks, consumer tests. Capstone: a model swap that does not break the client.
- OpenAPI
- Mocks
- Pact-style tests
- Capstone
Who this is for
Backend and platform engineers
You design APIs. Generative backends break the assumptions.
Tech leads
You need a contract other teams can build against while the model churns.
Prerequisites
- You have built or consumed HTTP APIs
- Python or TypeScript
- Basic auth concepts
Not a fit if
- GraphQL-vs-REST holy wars
- People who have never shipped an endpoint
Related: LLM API Integration · Software Engineering Fundamentals
Questions
REST or something else?
HTTP contracts, mostly REST plus streaming. The point is the failure model, not the fashion.
Will we build a gateway?
A small one, yes — enough to feel versioning and keys. Not a full internal platform.
Ready to start?
Four weeks to a contract that survives a model swap. Create an account to enrol.
Enrol now