Part 6 of 7 · 4 min read
Exercises
Try each exercise before opening its hint.
Easy
Easy 1: Find the five facts (25 minutes)
Open the documentation of any API and find, in under ten minutes: the base URL, how to authenticate, one example request, the rate limit and the error format. Write each with a link.
Done when: all five have a link, or you wrote "not documented".
Hint
look for a "Getting started" or "Quickstart" page first, then the reference.
Easy 2: Decode a reference entry (15 minutes)
Take a single endpoint from a reference page and write in plain words what it does, which parameters are required, which are optional, and what comes back on success and on failure.
Done when: a teammate could call it from your notes alone.
Easy 3: Spot the doc smell (15 minutes)
Which of these should make you verify before trusting? (a) an example with a model name that no longer appears in the model list, (b) a page last updated two years ago, (c) a changelog entry for the parameter you use, (d) a limit stated one way on one page and differently on another.
Done when: you marked a, b and d, and explained what to check for each.
Medium
Medium 1: Fill the checklist for a real API (45 minutes)
Choose one real API (a model provider you have a key for, or a public one such as GitHub's REST API). Fill the nine-row checklist from section 2 using only the official documentation. Add the URL of the page where you found each answer.
Done when: every row has an answer and a link, or "not documented" (itself a finding).
Hint
if the pricing page and the usage field disagree about units (tokens versus thousands of tokens), write both down.
Medium 2: Verify five claims (40 minutes)
From your checklist pick five claims (for example the rate limit, an error body, the default of a parameter, the pagination style, the auth header). Check each with a real curl -i request. Mark each confirmed, wrong or cannot test.
Done when: you have evidence for each mark, such as a pasted header or reply.
Hint
check a rate limit by reading the headers on a normal request, not by overloading the service.
Medium 3: Run the OpenAPI reader (25 minutes)
Run python openapi_summary.py in code/openapi-reader. Then find a real OpenAPI file (many APIs publish one, often called openapi.json or swagger.json) and run the script on it. Compare what happens with the three gaps in the table in section 4.
Done when: you have run it on a real spec and written down which gap, if any, it hit.
Hint
if the file uses $ref, the parameter is defined elsewhere in the file; you will need to follow the reference.
Hard
Hard 1: Teach the script one more fact (45 minutes)
Extend summarise so that integer query parameters print their default and maximum (the sample has limit with default 20 and maximum 100). Add a test using sample_openapi.json.
Done when: the output for GET /notes includes limit (query, default 20, max 100) and the tests pass.
Hint
schema is a dictionary; use .get("default") and .get("maximum").
Hard 2: Follow the $ref (60 minutes)
Make the reader resolve local $ref pointers such as #/components/parameters/Limit, so referenced parameters appear in the summary. Add a test with a small spec of your own that uses a reference, and a test for a reference that points nowhere (it must give a clear error, not a crash).
Done when: both tests pass and a real spec that uses references now shows its parameters.
Hint
a pointer like #/components/parameters/Limit splits on / after the #; walk the dictionary one key at a time.
Hard 3: The defaults audit (60 minutes)
Take a model API you will use in Level 2. List every parameter in its reference with its default. Write a short script that makes one request with all defaults and prints the status, the finish reason, the token usage and the response time. Then change exactly one parameter at a time and note what changed. I did not run this exercise (it needs your key), so your numbers are the ground truth.
Done when: you can state which default would most surprise a newcomer, with evidence from your own requests.
Hint
keep your key in an environment variable (module 6) and never paste it into the script.