Part 5 of 7 · 3 min read
Reading an OpenAPI file with code
A 40-line script that answers the checklist from a spec, and what it does not handle yet.
When an API publishes an OpenAPI file, a small script can answer the checklist for you. openapi_summary.py in code/openapi-reader reads a spec and prints, for each endpoint, what you must send, what you may send, the possible replies, and which replies are worth retrying (429 and the 5xx codes from module 3). The sample spec describes a fictional Notes API; the address and limits are invented. This is real output:
$ python openapi_summary.py
Notes API (fictional) v1.2.0
Base URL: https://api.notes.example/v1
Auth scheme 'bearerAuth': http bearer
GET /notes
List notes
must send: nothing
may send: limit (query), cursor (query)
replies: 200, 401, 429
retry on: 429
POST /notes
Create a note
must send: JSON body with: title
may send: Idempotency-Key (header)
replies: 201, 422, 429
retry on: 429
DELETE /notes/{id} DEPRECATED
Delete a note
must send: id (path)
replies: 204, 404
retry on: nothing listed
GET /health no auth
Health check
must send: nothing
replies: 200
retry on: nothing listed
In seconds you can see that creating a note needs a title, that POST accepts an idempotency key (so a retry can be made safe), that deleting is deprecated, and that /health needs no key.
What the script does not handle yet
The script is deliberately small. I tried it on three kinds of input it does not expect, and two of them crash it:
| Spec feature | What happens |
|---|---|
No servers entry |
KeyError: 'servers' |
A parameter given as a reference ({"$ref": "#/components/parameters/Limit"}) |
KeyError: 'name' |
| Parameters listed once for a whole path rather than per method | Silently ignored; they are missing from the output |
Real specs use references and shared parameters a lot, so Hard 2 asks you to fix the second. A tool that fails loudly on input it does not understand is better than one that prints a wrong summary, and the third row shows the opposite case: a quiet gap. That is a good reminder to treat any generated summary as a map, not the territory.
For the curious What a $ref is
To avoid repeating itself, an OpenAPI file can define a parameter once, under components, and point to it from many places with {"$ref": "#/components/parameters/Limit"}. The text after # is a path through the file: the key components, then parameters, then Limit. A reader has to follow that path to find the real definition.
What you will use daily at work
| Practice | What it looks like |
|---|---|
| Generated clients | Tools generate a typed client from an OpenAPI file, so you call functions instead of building requests by hand. |
| Contract checks in CI | A test compares your code or mocks with the current spec and fails on a mismatch. |
| API clients with saved requests | Tools such as Postman or Bruno, or plain curl files kept in the repository, replay your verification requests. |
| Changelog subscriptions | Teams subscribe to the provider's changelog or status feed so that deprecations are not a surprise. |
| A one-page cheat sheet per API | The checklist from section 2, kept next to the code. |
| Pinned SDK and model versions | Upgrades are deliberate, tested changes. |
Draft: to be checked against current tool documentation before this page goes live.
Interview angle
Answer in your head first, then open it.
How do you learn a new API quickly?
Quickstart first with curl, then authentication, then the reference for the endpoint I need, then limits and errors, then the changelog. I verify with real requests, including failure cases.
A model's answers are cut off mid-sentence. What do you check?
The output-token limit and its default, the finish or stop reason in the reply, and how much of the context window is used.
Why pin a model version?
Aliases move to newer models, which can change behaviour and cost without any change in your code.
What is OpenAPI good for?
One machine-readable description that docs, generated clients, tests and mock servers can all be built from.