Ask an API development company to retire version one before it designs version one.
Give the team two fictional consumers. One is an internal web application released every week. The other is a partner that upgrades twice a year and needs formal notice. Now change a required field, replace one permission, and shut down the old contract without losing a request.
The exercise sounds backward. That is why it works. A provider that thinks only in endpoints will discuss a new path and a deadline. A provider that builds APIs as products will ask who the consumers are, how they are identified, what compatibility means, which usage is visible, who can contact each owner, and what evidence permits shutdown.
API development services should cover that whole consumer journey. If the purchase ends when requests return 200, the buyer still has to invent onboarding, security, change, support, and retirement after dependencies already exist.
Start at the last day
Write a retirement card for the fictional API.
| Retirement field | Required answer |
|---|---|
| Consumer inventory | Which applications and partners still call the version? |
| Contract owner | Who may approve a breaking change or shutdown? |
| Replacement | Which contract replaces the old behavior? |
| Compatibility window | How long can old and new behavior coexist? |
| Notice route | How does each consumer receive and acknowledge change? |
| Usage evidence | Which calls prove that a consumer still depends on it? |
| Migration proof | What test shows the consumer works on the replacement? |
| Shutdown proof | What confirms traffic stopped and access was removed? |
This is a proposed buyer artifact. It turns “we support versioning” into a set of duties someone must fund.
Do not accept a plan that identifies consumers only by API key. Teams, environments, products, and accountable owners matter. One key may serve several workloads. One consumer may use several credentials.
Define the consumer job
Move backward from retirement to the first useful request. For each consumer, describe the job in business terms.
“Create order” is incomplete. State who is allowed to create which kind of order, what identity makes a retry safe, which validation belongs to the API, what final evidence the caller receives, and how the caller learns that later processing failed.
Keep the first contract narrow enough to explain. An API that exposes the database schema moves internal change directly into every client. Start from stable business concepts and actions. Record terms whose meaning is disputed.
The OpenAPI Specification defines a language-agnostic description for HTTP APIs that tools and people can use to understand a service. A machine-readable contract is useful, but it does not decide the business boundary for you. Generate tests and documentation from the contract where it helps; keep authority and meaning in the design discussion.
Make failure part of the contract
Clients need to know more than success and error.
For each operation, define:
- which validation failures are permanent;
- which failures may be retried;
- how long a client should wait;
- how duplicate intent is recognized;
- whether work can continue after the response;
- how a client checks final state;
- which correlation value appears in logs and support records.
Use a consistent error shape. RFC 9457 defines a problem-details format for HTTP APIs. It is one option, not a requirement for every protocol. Whatever format you choose, clients should be able to distinguish invalid input, missing authority, conflict, throttling, dependency failure, and an unknown server fault without parsing prose.
Run a timeout after the server commits the change but before the client receives the response. The retry must not create a second business effect. Then run two different requests with the same idempotency identity and confirm the conflict is visible.
Authorize the object and the action
Authentication establishes who or what is calling. Authorization decides what that identity may do to this resource now.
Model actions such as read, create, approve, cancel, export, and administer separately. Test access across tenants or accounts. Test indirect object references and bulk endpoints. A user who may read one order should not gain another by changing an identifier.
The OWASP API Security Top 10 is an awareness resource for common weaknesses across API design, development, and maintenance. Use its categories to challenge the design, then convert applicable risks into specific tests and controls. Passing a generic scanner does not prove object-level authorization.
NIST SP 800-228 organizes API protection across pre-runtime and runtime stages. Require the provider to map security work to the lifecycle: design review, schema and policy checks, deployment controls, runtime enforcement, logs, incident response, credential rotation, and retirement.
Give the consumer a first hour
Acceptance should include a fresh consumer team. Give it the public documentation, credentials for a safe environment, and one goal. Do not let the builder sit beside the team.
Observe where the consumer stops:
- Can it find the correct contract and environment?
- Can it obtain and scope a credential?
- Can it make a valid request from an example?
- Can it recognize and repair invalid input?
- Can it find a request in logs or support using a correlation value?
- Can it test a retry without creating a duplicate effect?
Every private message from the builder is missing product surface. Put the answer into the contract, guide, example, error, or support route, then rerun with another person.
The goal is not a pretty portal. It is independent adoption.
Release without surprising consumers
Classify changes before merging them. An additive optional field may be compatible for one client and break another client that rejects unknown fields. A widened enum may look additive and still break generated code. A semantic change can keep the same schema while changing money or access.
Maintain representative consumer contract tests. Include at least one older supported client. Publish a change record that explains behavior, migration, and timing. For breaking work, run old and new versions together only as long as the operating plan can support both.
The provider should state how it detects an accidental break in continuous delivery. Our API contract testing guide owns that release-gate workflow. The service purchase should make it real for the selected stack and consumers.
Operate by business effect
Latency and error rate matter, but they are not enough. Monitor accepted business actions, rejected actions, duplicate attempts, asynchronous backlog, dependency failures, and final outcomes.
A 202 Accepted response may be healthy while the downstream queue is stuck. A low error rate can hide one consumer that has lost every request because its credential expired. Segment evidence by operation, consumer, environment, version, and consequence.
Set quotas from the workload and failure plan. State what happens when a caller exceeds one. Silent dropping is not a policy. If the API depends on another system, define whether the caller waits, receives a retriable failure, or gets an accepted job whose final status is available elsewhere.
Give support a way to trace one business request without exposing sensitive payloads. The operator should see identity, authorization decision, contract version, processing stage, dependency result, and final state.
Run the retirement rehearsal
Return to the retirement card. Stand up a second contract with one intentional breaking change. Migrate the internal consumer. Leave the fictional slow partner on the old version.
Prove that the team can:
- identify traffic from each consumer;
- issue and track notice;
- run both contracts without confusing support;
- test the replacement with consumer-owned cases;
- observe zero remaining legitimate use;
- disable the old route and credentials;
- restore service if the shutdown evidence was wrong.
Do this before a real partner depends on the interface. Retirement is cheaper to learn when the consumers are invented.
Normalize the proposals
Give every provider one consumer story, one forbidden action, one ambiguous retry, and the same retirement card. Compare evidence across these areas:
| Area | Evidence |
|---|---|
| Contract | Domain model, examples, errors, compatibility rules |
| Security | Threat review, authorization tests, credential lifecycle |
| Delivery | Generated checks, environments, release and rollback |
| Adoption | Independent first-hour test and support path |
| Operation | Consumer-level metrics, traces, alerts, incident drill |
| Change | Version policy, migration proof, deprecation rehearsal |
| Transfer | Repositories, infrastructure, runbooks, ownership, exit |
Framework expertise matters after the boundary is clear. A long technology list cannot compensate for a service that nobody can change safely.
What to bring to gmware
Bring one proposed consumer, the business action it needs, a sample request or existing workaround, and the strongest action it should never be allowed to perform. If an older interface exists, bring one failure and one breaking change from its history.
We can use that packet to draft the consumer contract, security boundary, first failure test, and retirement card. The result may be a custom API, a smaller adapter, an existing product, or a decision not to expose the capability. Endpoint zero comes later.