The reference says what the API is. The changelog says how it got that way, and it is the first thing a consumer reads when something that worked yesterday doesn’t today.
## 2027-03-01
- Deprecated: version v1. It stops responding on 2027-09-01.
See the migration guide.
## 2027-02-10
- Added: `status` on the license object (v2 only).
- Added: `Idempotency-Key` is accepted on POST /licenses.
Every entry has a date. A consumer is always asking “what changed since last Tuesday?”
Entries are written for the consumer. “Refactored the driver” is not a changelog entry. Nothing changed for them. “Timeouts from the provider now return 504 with a code” is.
Additions are listed too. A changelog that only records breakage teaches people that every entry is bad news.
Write the entry in the pull request that makes the change. It is the same habit as the documentation notes in Chapter 14: the only update that reliably survives is the one that travels with the code.
Protect the Documentation, or Don’t
Decide who can read your API’s reference.
For a public API, the documentation is marketing and should be open. For an internal one, like the License API, the reference describes every endpoint of a system that manages credentials, and there is no reason for it to be readable from the internet. Put it behind the same kind of check as the API, and remember that the OpenAPI document is as revealing as the pages rendered from it.
What should never be in either: a real token in an example, a real consumer’s name, a hostname of something internal. Examples are copied. Assume whatever is in an example will be pasted into a terminal by someone, somewhere.
Chapter 15 Summary
- Lead with a call that works. A consumer’s first minute decides whether the rest is read.
- Describe the API in OpenAPI, and generate that description from FormRequests, Resources, and routes.
- A generator can only read what is declared. Staying inside the framework is what makes the API describable.
- Write the meaning yourself: what each endpoint is for, and the guides.
- Commit the generated document. Fail the build when it is stale, and when a change is breaking.
- Document every error with what the consumer should do next.
- Keep a dated changelog, written for consumers, updated in the pull request that makes the change.
- Decide who may read the documentation, and keep real secrets and names out of examples.