API Product Management
Treating an API as a product with a lifecycle — versioning, deprecation, adoption metrics and a support commitment — rather than as an implementation detail.
Definition
An API consumed outside your team is a product. It has users, a lifecycle, a support obligation and a cost of change that is paid by other people. Managing it means deciding deliberately what you will promise, for how long, and how you will withdraw it.
Versioning strategies and their real costs
| Strategy | Cost |
|---|---|
| No versioning, additive only | Cheapest to run; requires genuine discipline forever |
| Version in the URL | Simple and visible; encourages forking the whole surface |
| Version in a header | Cleaner; less discoverable, easier to get wrong |
| Date-based pinning per consumer | Excellent consumer experience; substantial provider complexity |
Date-based pinning — where each consumer is pinned to the version current when they integrated, and the provider maintains compatibility transformations between versions — gives consumers the strongest possible guarantee. The cost is that the provider carries a growing set of transformations indefinitely. It is the right choice when the consumer base is large, external and commercially important, and it is over-engineering for an internal API with three known callers.
Deprecation done properly
- Instrument first. You cannot deprecate what you cannot measure. Per-consumer usage of every endpoint and every field is the prerequisite, and it should exist before the first version ships.
- Announce with a date and contact the users directly. A changelog entry is not notice.
- Return deprecation headers, so it appears in the consumer's logs.
- Brownouts — brief, scheduled periods where the endpoint returns errors — surface the integrations nobody responded to, while there is still time to fix them.
- Withdraw, with a documented exception process for the partner who genuinely cannot move.
Industry example
Developer-facing platforms like GitHub demonstrate the discipline at scale: a documented deprecation policy, long notice periods, headers that warn in-band, and a strong bias toward additive change because the consumer base is effectively unbounded and includes automation nobody can contact.
The lesson worth taking is that the constraint is not technical. Removing a field is trivial; knowing who depends on it, reaching them, and giving them time is the work. An organisation that has not instrumented per-consumer field usage cannot deprecate anything safely, regardless of how good its versioning scheme is.
Failure scenarios
- Breaking change shipped as a minor version, discovered by consumers in production.
- No usage instrumentation, so deprecation is guesswork and nothing is ever removed.
- Versions proliferating with no retirement, so the provider maintains six surfaces.
- Internal APIs treated as products — full versioning ceremony for three known callers who could simply be updated.
Interview question
"How do you know it is safe to remove a field from a public API, and what would you have needed to build to know that?"