Paths/Backend Engineer/API Design / Resource Modelling
Write an OpenAPI Contract
The specification is how clients are generated and how nobody has to ask what the endpoint returns. Write it for the orders collection.
Validator
IDLE — checks run live as you type commands; submit when done
01Requirements
live checks- Directory ~/api/openapi exists○
- File ~/api/openapi/orders.yaml exists○
- The spec declares its version, its paths and the responses○
- The list operation documents a 200 response○
02Walkthrough
5 steps- 01
Create the api directory
Contracts live in the repository, not in a wiki - one directory per surface.
mkdir -p ~/api/openapi - 02
Write the spec header
openapi declares the specification version. Paths hold the operations, and every operation documents its responses.
echo 'openapi: 3.0.3\ninfo:\n title: Orders API\n version: 1.0.0\npaths:\n /orders:\n get:\n summary: List orders\n responses:\n "200":\n description: A page of orders' > ~/api/openapi/orders.yaml - 03
Document the response shape
Describe the body with a schema so client generators know what they are parsing.
echo '\n content:\n application/json:\n schema:\n type: array\n items:\n type: object' >> ~/api/openapi/orders.yaml - 04
Verify the contract
cat prints the spec. Read it as somebody who has never met your service.
cat ~/api/openapi/orders.yaml - 05
Submit for validation
The validator checks the version, the paths, the operation and the responses.
03Stuck?
0 of 3 revealedTake a hint without losing the lab — each one points at the thing to look at, not at the answer.
04AI Tutor
guides, never solvesTell me what you're stuck on — I'll nudge, not solve. Which requirement are you looking at?
04Notebook
saved locally in this browserlearner@lab — ubuntu:24.04
Session is disposable
↑/↓ recalls commands · Ctrl+Enter submits · type help for the command list