API as a Promise: Designing for Systems You Don’t Control
Yes, an API is fundamentally a promise—a contract that specifies how two systems will interact, even when you have no control over the other side. This promise defines the requests you can make, the responses you can expect, and the behavior that will remain stable over time.
What an API Promise Really Means
When you design an API, you are making a commitment to every current and future consumer. Unlike a function call within your own codebase, an API is consumed by systems you may never see, written in languages you don’t use, and operated by people you’ve never met. The promise is that if a client sends a valid request, it will receive a predictable response—or a clear error explaining why not. This stability is what allows third-party developers to build applications on top of your service without constant coordination.
Why the Promise Matters More Than the Implementation
The internal implementation of an API can change completely—databases can be swapped, algorithms optimized, servers migrated—but the external contract must remain intact. This separation is what makes software ecosystems possible. Consider a payment gateway: merchants rely on the API to charge customers, refund orders, and retrieve transaction history. If the gateway changes its response format or renames a field without notice, every merchant’s integration breaks simultaneously. The promise protects the consumer from the provider’s internal churn.
How API Promises Are Enforced
Promises are enforced through several mechanisms that work together:
- Versioning: APIs are versioned (e.g., /v1/, /v2/) so breaking changes are introduced in a new version, leaving the old one operational.
- Deprecation policies: Providers announce that a feature or version will be removed on a specific date, giving consumers time to migrate.
- Schemas and documentation: OpenAPI or JSON Schema documents define the exact structure of requests and responses, making the promise explicit.
- Semantic versioning: Version numbers indicate the type of change—major for breaking, minor for backward-compatible additions, patch for fixes.
Common Ways the Promise Gets Broken
Even with good intentions, APIs break promises. The most common failures include:
- Silent changes: Adding a required field to a response, changing the type of an existing field, or altering error codes without documentation.
- Rate limiting without notice: Suddenly throttling requests when a consumer exceeds an undocumented limit.
- Inconsistent error handling: Returning 200 OK with an error body in some cases, and a 500 with a different format in others.
- Timeouts and latency: The API becomes so slow that the consumer’s own timeout fails, even though the request eventually succeeds.
Designing for Systems You Don’t Control
To make a promise you can keep, design with the consumer’s perspective in mind:
- Make responses self-descriptive: Include a version field, a request ID, and meaningful error codes.
- Never change a field’s meaning: If a field called “total” has always been the sum without tax, don’t suddenly include tax.
- Additive changes are safer: Add new fields or endpoints rather than modifying existing ones.
- Provide a sandbox environment: Let consumers test against a non-production version to verify their code.
- Document everything, including limits: If there’s a rate limit, publish it and return a clear 429 response with a Retry-After header.
How to Choose an API (and What to Check)
When you’re the consumer, you need to evaluate the promise before you commit. Check the API’s documentation for a changelog, versioning policy, and deprecation notices. Look at the error messages—are they specific enough to debug without contacting support? Test the API’s behavior with edge cases: what happens when you send an invalid parameter, or exceed the rate limit? A robust API will fail gracefully. Also, check if the provider offers a status page and a history of uptime; a promise is worthless if the server is often down.
Comparison: REST, GraphQL, and Webhooks
The promise differs by architectural style. REST promises a uniform interface with HTTP methods and status codes—it’s simple and widely understood. GraphQL promises that you can query exactly the data you need, but it puts more responsibility on the client to construct valid queries, and the server must promise to resolve them efficiently. Webhooks promise to deliver events to a URL you provide, but they require you to handle retries and out-of-order delivery. Each style has its own failure modes: REST can break with a new field, GraphQL can become slow with deeply nested queries, and webhooks can be lost if your endpoint is down.
Costs and Safety Considerations
API promises have real costs. For providers, maintaining backward compatibility means extra code, testing, and documentation. For consumers, there’s the cost of keeping up with changes—reading changelogs, updating SDKs, and re-testing. Safety is also a concern: an API that doesn’t validate inputs can expose your system to injection attacks or data leaks. Always use HTTPS, authenticate properly, and validate all data received from an API, even if it’s from a trusted provider. Never assume an API will return exactly what you expect; always check the response status and handle errors.
Frequently Asked Questions
What happens if an API breaks its promise?
If a provider makes a breaking change without a deprecation period, consumers’ applications will fail. The provider may face backlash, loss of trust, and migration of users to competitors. In extreme cases, legal action could be taken if a service-level agreement (SLA) exists, but most public APIs have no such guarantee.
Can I trust an API that is still in beta?
Beta APIs are explicitly not stable—they may change at any time. You can use them for experimentation, but for production, wait for a stable version. If you must use a beta API, isolate it behind your own adapter so a change only affects that layer.
How do I know which version of an API I’m using?
Most APIs include a version in the URL path (e.g., /v2/users) or in a header. Some also return a version field in the response. Check the documentation for the exact mechanism. If you’re using an SDK, it usually pins a specific version.
What is the difference between backward compatibility and forward compatibility?
Backward compatibility means a new version of the API still works with old clients. Forward compatibility means an old version of the API can handle requests from new clients (which is rare). In practice, you should design for backward compatibility and document any forward-compatible features as experimental.
Is it better to build my own API or use a third-party one?
If the third-party API is stable, well-documented, and meets your needs, it saves time and maintenance. However, you’re dependent on their promise. If the API is critical to your product, consider building a thin wrapper that can be swapped out if needed, or negotiate a contract with the provider.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.