Part 3 of 7 · 3 min read
A reading order that saves time
Go from wide to narrow, and keep a short checklist for every API you use.
You almost never need to read the whole reference. Go from wide to narrow:
- Quickstart. Reproduce its example exactly, with
curlor a short script, before you change anything. That proves your key, network and account work. - Authentication. Note the header name, the key format, and whether keys are tied to a project, region or spending limit.
- The reference page for your endpoint. Look for required inputs, defaults and the shape of the reply.
- Limits and errors. Rate limits, maximum request size, timeouts, the error body format, and which codes are safe to retry (module 3).
- Changelog. Look for deprecations and recent changes, especially when an example fails.
Keep a short note for every API you use, with the answers to these questions:
| Question | Where to look | Why it matters |
|---|---|---|
| What is the base URL and version? | Quickstart, servers section | The wrong version behaves differently |
| How do I authenticate? | Authentication page | Header name and format differ between providers |
| What is required, and what has a default? | Reference table | Defaults silently shape every call where you set nothing |
| What are the limits? | Rate limits and quotas page | They decide concurrency and retries (modules 3 and 4) |
| What does an error look like? | Errors page | Your error handling has to parse it |
| How is a list paginated? | The list endpoint | Otherwise you only ever see the first page |
| Is a repeat call safe? | Idempotency section | Decides whether you may retry a POST |
| What does it cost? | Pricing page, usage field in replies | Agents can loop and spend quickly |
| What is deprecated? | Changelog, deprecated flags |
Do not build on what is going away |
Defaults are the hidden parameters
Here is a reference entry for a made-up model API. Read it as you would a real one:
The parameter you did not set is often the one that explains a surprise. In this entry max_tokens has a default of 256. A long answer would stop at 256 tokens in the middle of a sentence, with no error, because the API considers that it did what you asked. Other examples: a default temperature that makes results differ from run to run, or a default timeout shorter than your slowest call (module 3).
When behaviour is strange
List every parameter and its default before you change your prompt. Then change one thing at a time.
Check yourself
- Why do you reproduce the quickstart before changing anything?
- In the entry above, what would you check if answers were cut off?