API design: contracts, versions, resilience
You design long-lived APIs with consistent naming, error formats, paging, versioning, idempotency and rate limiting, and protect the contract with tests.
Level 301 · 18 lessons · 15 practice labs
Lessons
The contract
- Resource modelling and naming
- Contract first: designing with OpenAPI
- Error format: problem+json
- Paging styles: offset and cursor
- Filtering, sorting and field selection
- Short task: fix a badly designed API
Change and resilience
- Versioning and backward compatibility
- Deprecation and announcing it
- Idempotency keys
- Concurrent updates: ETag and If-Match
- Rate limiting and its headers
- Long-running jobs: 202 and a status URL
- Webhooks and signed notifications
- Short task: make a payment sent twice a single record
Quality
- Contract tests
- Comparing GraphQL and REST
- API observability: logs, metrics and trace IDs
- Capstone: design and build a booking API
Practice labs
- Turn verb-filled URLs into resources: Turn endpoints like /getUsers and /deleteOrder into a design based on resources and HTTP methods.
- Move error bodies to problem+json: Move an API that returns errors in a different shape on each endpoint to a single problem+json format.
- Catch a break with a contract test: Write the contract a mobile client expects as a test and catch an API field rename in CI.
- Find the record offset paging skips: Show that a record gets skipped when new ones are added between pages and explain why.
- Page transactions with a cursor: Move an account transactions API from offset to cursor paging and choose a stable sort key.
- Design field selection and a filter syntax: Add a fields parameter and a safe filter syntax for a mobile client and measure the drop in response size.
- Spot a breaking change: Decide which of the differences between two versions' responses will break clients.
- Announce a field that will be removed: Add Deprecation and Sunset headers for a field that will be removed and write a migration note in the docs.
- Run two API versions side by side: Build a routing layer that serves v1 and v2 from one codebase without duplicating the shared logic.
- Trace an order created twice: Find in the logs where the same order was created twice and show which retry caused it.
- Prevent a lost update with ETag: When two admins edit the same product at once, reject the second write with 412 using If-Match.
- Make the refund endpoint idempotent: Add idempotency keys to refund requests and return a conflict error when the same key arrives with a different body.
- Read rate-limit headers: Read the remaining quota and reset time from an API's headers and work out how many more requests you can send.
- Verify a webhook signature: Verify the HMAC signature and timestamp of notifications from a payment provider and reject forged ones.
- Serve a long report with 202 and a status URL: Turn a minute-long report generation into a flow with 202, a status URL and a download link when it finishes.
About this course
You design long-lived APIs with consistent naming, error formats, paging, versioning, idempotency and rate limiting, and protect the contract with tests.
What you will learn
- The contract
- Change and resilience
- Quality
Prerequisites
You should be comfortable with the level 101 and 201 topics of the same path.
Lab environment
Lessons run in your own Kali Linux terminal in the browser, connected to a private lab network. Nothing to install.
Frequently asked questions
- Is this course right for my level?
- The course is at level 301; it assumes you know the topics of the lower-level courses.
- Is there anything to install?
- No. Every lesson runs in your own lab environment that opens in the browser.
- How do lessons work?
- Each lesson has 8 to 10 steps and a short quiz. Early steps show the command to type, later steps give less help; if two attempts fail, the solution opens.
- Can I try it for free?
- Yes. The first three lessons of every course are free.