Offering an API: What It Commits You To

An API is a promise about the future

Once a customer writes code against your API, changing it breaks their system. That constrains your ability to change your own data model, sometimes for years.

That constraint is worth accepting when the API genuinely drives adoption or retention. It is not worth accepting because it seemed like a good idea for a feature list.

What you are committing to

• Stability. Breaking changes require versioning and a migration period.
• Documentation that is accurate, with working examples.
• Support for developers, which is different from supporting end users.
• Availability, since customers' systems now depend on yours being up.
• Rate limiting and abuse handling, because someone will loop.

Design decisions worth getting right early

1. Authentication — keys scoped per customer, revocable, never shared.
2. Versioning from day one, even with one version. Retrofitting it is painful.
3. Pagination on every list endpoint, always, however small the data seems now.
4. Consistent errors with codes and useful messages.
5. Idempotency for anything that creates or charges, so retries are safe.
6. Webhooks alongside polling, so customers are not forced to poll you.

Pagination is the one that bites. An endpoint that returns everything works fine until a customer with ten thousand records tries it, at which point it takes down more than their request.

Documentation is the product

For an API, documentation is the interface. Working examples in common languages, a way to try requests, and honest descriptions of what each field means and when it can be null.

Generated documentation from the code is a good baseline and rarely sufficient on its own — the guidance about how to accomplish a task is what developers actually need.

Watch what it does to support

API customers generate different support: integration questions, unexpected data, rate limit complaints, and reports that something changed. Budget for it, and give developers a route that does not go through general support.

Deprecate carefully when you must

Long notice, clear migration guidance, and usage data so you know who is affected. API deprecation with short notice is how a technical decision becomes a churn event.

Contact the accounts using the old version individually. There are usually fewer than you fear and the personal contact prevents most of the damage.

Frequently asked questions