Most APIs work fine on day one. The problems show up eighteen months later, when the first breaking change is needed and there's no versioning strategy, or when a single integration partner accidentally takes the whole system down with an unthrottled retry loop. Production-ready API design is mostly about decisions that don't matter until they suddenly do.
Versioning: decide before you need it
The question isn't whether you'll need to make a breaking change — you will. The question is whether existing integrations break when you do. Three common approaches:
| Strategy | Example | Trade-off |
|---|---|---|
| URL versioning | /api/v2/orders | Explicit and simple, but encourages duplicating whole endpoints |
| Header versioning | Accept: application/vnd.api+json;version=2 | Clean URLs, but less discoverable and easy to forget in client code |
| Additive-only | Never remove fields, only add optional ones | Avoids versioning entirely, but limits how much you can actually change |
For most B2B APIs, URL versioning is the pragmatic default — it's obvious in logs, easy for partners to reason about, and doesn't require special client tooling.
Authentication and authorization aren't the same problem
Authentication answers "who is this." Authorization answers "what are they allowed to do." API keys, OAuth tokens, and JWTs solve the first problem. Scopes and role checks solve the second — and they need to be enforced at every endpoint, not just checked once at login. A common, expensive mistake is authenticating a request correctly and then trusting the client to only request things it's allowed to see.
Rate limiting protects you and your integrators
Rate limits aren't just defense against abuse — they're what keeps one integration partner's bug from degrading service for everyone else. At minimum:
- Per-key limits, not just global ones.
- Clear
429responses with aRetry-Afterheader, not a silent drop. - Different limits for read vs. write operations — writes are usually more expensive.
Observability: you will need to answer "what happened" under pressure
When a partner reports "your API returned an error at 3am," you need to be able to answer that in minutes, not hours. That requires structured request logging (who, what endpoint, what status code, how long it took), error tracking with enough context to reproduce the issue, and metrics on latency and error rate per endpoint — not just an aggregate uptime number.
Documentation is part of the API, not an afterthought
An API without accurate, versioned documentation (OpenAPI/Swagger, generated from the actual code where possible) effectively doesn't exist for external integrators. Hand-written docs drift out of sync with the implementation within weeks unless they're generated from the same source of truth.
Common mistakes
- No pagination on list endpoints. Works fine with ten records, breaks the client at ten thousand.
- Inconsistent error formats. Every endpoint should return errors in the same shape, with a machine-readable code, not just a human-readable message.
- Skipping idempotency keys on write endpoints. A retried request during a network blip shouldn't create a duplicate resource.
- Auth checks scattered across the codebase. Centralize authorization logic — scattered checks are how permission bugs slip through.
Recommended approach
Pick a versioning strategy before your first external integration exists, not after. Enforce authentication and authorization as separate, explicit layers. Build rate limiting and structured logging in from the first deploy — retrofitting observability after an incident is far more expensive than building it in from the start.
Conclusion
A production-ready API isn't the one with the most features. It's the one your partners can build on without fear that a change will break them silently, or that a spike in traffic from one client will take down the system for everyone else.
Kiaanlab builds documented, versioned APIs with rate limiting and auth built in from the first release. Tell us what you're integrating with and we'll help you scope it right.