iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
An API becomes a promise the moment someone else writes code against it. A partner integration, a mobile build that users never update, or a script a colleague wrote three years ago will keep calling your endpoints long after you have moved on, and you cannot choose when they upgrade. What you control is the contract they can observe: resource names, field meanings, status codes, error shapes, and what a repeated call does. Designing for systems you no longer control means keeping that contract stable, changing it compatibly by default, making retries safe, and making failures diagnosable and protected.
What clients actually depend on
Consumers rarely read your documentation closely enough to notice what you intended. They depend on whatever the API does reliably, including behaviour you never meant to promise. Microsoft’s guidance on Web API design notes that the provider may have less control over partner-built clients than over the API itself, and recommends continuing to support existing clients while enabling new features. Treat that as the starting assumption, not an edge case.
The table lists each layer of the promise and the question to answer before release.
Recommended Free Tools
| Layer | What clients come to rely on | Question to answer before release |
|---|---|---|
| Resource model | Names, identifiers, and relationships between things | Does this reflect a business concept, or a table someone happens to have? |
| Payload | Field names, types, units, and meanings | Can a client that ignores unknown fields still work? |
| Behaviour | Status codes, error bodies, pagination, and ordering | Which codes will clients branch on, and are they documented? |
| Mutations | What happens when the same write is sent twice | What does a client learn after a timeout? |
| Versions | How a client selects a version and how long it stays available | How will consumers of the old version learn about the change? |
| Operations | Availability, latency, and the ability to diagnose a failed call | Can a consumer’s support team trace one failed request? |
| Security | Authentication scheme, permissions, and how access is revoked | Who may call which operation, and how is that enforced at runtime? |
Model the boundary, not the storage
The most common way APIs break consumers is not a deliberate change. It is an internal refactor that was never meant to be visible. If the API mirrors the database, every schema migration becomes a client migration. Microsoft’s API design guidance advises against exposing internal implementation details or mirroring a database schema, and says an API should change primarily when functionality is added, not when code is refactored or storage changes.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Compare two responses for the same customer. The first leaks the storage layout:
GET /tbl_cust/10442
{ "cust_id": 10442, "addr_line1": "12 High Street", "flg": 3 }The second describes the business concept:
GET /customers/10442
{ "id": "10442", "postal_address": { "line1": "12 High Street" }, "marketing_consent": true }The second shape lets you split the customer table, rename a flag column, or move addresses into another service without changing what clients receive. Encode meaning in names and documented values. A boolean or a string enumeration with written definitions is far safer than a numeric flag whose meaning lives in an internal spreadsheet.
Make compatible change the default
Compatibility depends on how existing clients handle a response, not only on the change itself. Microsoft’s guidance draws the basic line: a new field can be ignored by existing clients, while removing or renaming a field can break them. The table applies that test to common changes.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Change | Usually compatible? | What decides it |
|---|---|---|
| Add an optional response field | Yes | Clients must ignore unknown fields. State that rule in the documentation and in any SDK you publish. |
| Add an optional request parameter | Yes | The default must reproduce the behaviour the old version had. |
| Add a new endpoint | Yes | Existing clients never call it, so nothing they depend on has moved. |
| Remove or rename a response field | No | Any client reading the field breaks, often silently. |
| Change a field’s type or unit, keeping its name | No | Changing cents to pounds in the same field breaks parsing and arithmetic even though the name still matches. |
| Make an optional request input required | No | Requests that used to succeed now fail validation. |
| Give an existing value a new meaning | No | Clients still send or read the old value and get different results. This is often the hardest change to notice. |
| Tighten validation on existing input | Usually not | Requests that previously succeeded now return errors. |
When a change fails this test, introduce a new version and keep the previous one running. Microsoft’s guidance recommends exactly that when a breaking change is unavoidable. The next section covers how versions are selected and retired.
Rank #2
Versioning as a lifecycle
Home Office engineering guidance on designing and maintaining an API says an API should include some form of versioning, consider how a version will be deprecated, and decide how that deprecation will be communicated to consumers. It names URI paths, query parameters, and headers as places a version can live, and asks teams to choose a strategy consistently, either per endpoint or across the whole API. This is guidance rather than proof that one mechanism is universally best, so the trade-offs below are real and depend on your consumers.
Where the version lives
| Location | Example | Clarity for consumers | Cost for the provider |
|---|---|---|---|
| URI path | /v2/customers/10442 | Visible in logs, browser address bars, and bug reports | Each major version is a separate route, so documentation and routing are duplicated. |
| Query parameter | /customers/10442?api-version=2 | Easy to add and to test in a browser | Clients omit it easily, and every endpoint, cache, and gateway must handle it consistently. |
| Header | Accept: application/vnd.example.v2+json | Keeps URLs stable across versions | Invisible in a plain address bar and easy to leave out, so SDK and documentation support matter more. |
Retire a version in stages
- Publish the replacement version and the end-of-support date in the developer documentation when the new version ships, not when the old one is about to close.
- Add a notice to every response from the deprecated version, such as a deprecation header or a documented warning field, that names the replacement and the end date.
- Identify which consumers still call the old version, using client identifiers or API keys, and contact them directly rather than relying on a changelog.
- Keep the old version running through the announced window, and watch its traffic so you know how many consumers have not moved.
- After the date passes, return 410 Gone with a body that points to the replacement, instead of an unexplained 404, for a period long enough that stragglers can find the explanation.
Retries, idempotency, and ambiguous failure
A timeout does not tell the client what happened
When a client sends a POST to a payments endpoint and the connection drops before a response arrives, it knows nothing about the outcome. The payment may have been created, rejected, or never received. A retry might charge twice, and giving up might lose a payment. This ambiguity is the central reliability problem for consumers you do not control, because they will retry whether or not you designed for it.
Which requests a client can repeat
RFC 9110, the HTTP Semantics standard published by the RFC Editor, distinguishes idempotent methods because a client can repeat them automatically after a communication failure, before it has read a response. It addresses non-idempotent requests directly:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11“A client SHOULD NOT automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are actually idempotent, regardless of the method, or some means to detect that the original request was never applied.”
RFC 9110, Section 9.2.2, RFC Editor, “HTTP Semantics”
The table applies that rule to common methods. The idempotency column reflects RFC 9110’s own classification.
| Method | Idempotent under RFC 9110? | Retry guidance |
|---|---|---|
| GET, HEAD | Yes (safe methods) | Repeat after a failure, with backoff. |
| PUT | Yes | Safe when the body carries the full resource state. A body that says “add 5” is not. |
| DELETE | Yes | A repeat is safe, but a second call may return 404. Treat that as “already deleted” when deletion was the goal. |
| POST | No | Do not repeat unless the endpoint accepts an idempotency key or the client can check whether the first attempt was applied. |
| PATCH | Not in RFC 9110’s list of idempotent methods | Treat as non-idempotent unless you have designed the patch operations to repeat safely. |
Idempotency keys make writes retryable
AWS Well-Architected guidance on making responses idempotent describes an idempotency token: the client generates a unique value, sends it with the request, and reuses the same value on every repeat. The service records the outcome, so a repeat returns the original result instead of creating a second record. This is a design pattern that removes duplicate-effect risk for the operation it covers. It is not a guarantee that a distributed system executes every request exactly once.
The token is only as good as the behaviour you specify around it, and no single standard fixes these choices. Write them into the contract:
- Scope: is a key unique per account, per client, or per endpoint?
- Retention: how long is a key remembered, and what happens to a request that arrives after expiry?
- Replay: does a repeat receive the stored original response, including its status code, or only a summary?
- Mismatch: what happens when the same key arrives with a different body? Rejecting it is a common choice, and the rejection should be a distinct, documented error.
- In progress: what does a repeat receive while the first attempt is still running?
Asynchronous work: 202 means accepted, not finished
Microsoft’s API design guidance says an HTTP 202 response indicates that a request was accepted for processing, not that processing has completed. Make that distinction explicit in the contract, and tell clients how they will learn the outcome: a status resource they can poll, a callback, or both.
POST /report-jobs
202 Accepted
Location: /report-jobs/7781
GET /report-jobs/7781
{ "id": "7781", "status": "running" }Document every status value, including the terminal ones and what a failed job’s error looks like. A client that cannot tell “still running” from “lost” will resubmit the original POST.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Operating the promise: diagnosis and errors
A consumer you cannot call will still open a support ticket. Design so that one failing request is enough to diagnose the problem.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches- Return appropriate HTTP status codes and keep each code’s meaning stable. Clients branch on codes, so changing a 409 to a 422 changes behaviour.
- Include a request identifier in every response, errors included, and log it server-side so a consumer can quote it.
- Give errors a stable, machine-readable code in the body alongside a human-readable message. Messages can change freely; codes should rarely change.
Home Office guidance asks for a way to observe API health and trace activity, and recommends aggregated application logs and metrics. Be deliberate about what you log. Request and response bodies often contain personal or sensitive data, so record identifiers and outcomes by default, and capture payloads only under controls you can explain.
When a consumer reports a failure
- Ask for the request identifier, the timestamp with its time zone, the endpoint called, and the version selected.
- Search server logs for that identifier. If it does not appear, check whether the request was rejected before reaching the service, for example at a gateway.
- Compare the status code with its documented meaning, and ask whether the consumer retried. Duplicate records point to retry handling rather than the endpoint itself.
- If the request reached the service, check the version and headers it used against the payload it sent. A version or header mismatch explains many unexpected responses, so rule it out before assuming the endpoint is at fault.
Security is part of the promise
NIST Special Publication 800-228, “Guidelines for API Protection for Cloud-Native Systems,” received a March 2026 update, SP 800-228-upd1, published March 13, 2026. It addresses API risk factors across development and runtime, and recommends basic and advanced protection controls. Each choice is presented with its advantages and disadvantages, so teams can adopt controls incrementally according to their risk. The scope is cloud-native systems, so apply it to other architectures with judgement.
Home Office guidance adds input validation, appropriate security practices, authentication and authorization, testing, and consideration of scalability to the same list. In practice this means:
- Authenticate every request, and authorize each operation against the resource it touches rather than only at the endpoint level.
- Validate every input at the boundary and reject what the contract does not allow, using the error codes described above.
- Assess API risk at design time and again at runtime, not only before launch.
- Include authentication and validation failures in automated contract tests, so a regression is caught before a consumer finds it.
Choosing an interface style
Microsoft’s guidance separates public APIs from service-to-service APIs. Public interfaces usually need client compatibility and broad interoperability, while internal calls may prioritise payload size and serialization performance. Its comparison covers REST over HTTP, RPC, and binary serialization. Treat the table as a set of trade-offs, not a ranking.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Style | Main strength | Main cost | Usually fits |
|---|---|---|---|
| REST over HTTP with JSON | Any HTTP client can call it, and gateways and caches understand status codes and methods | Verbose payloads, and resource modelling takes discipline | Public and partner APIs |
| RPC over HTTP | Maps directly to operations, which suits internal teams | Operation names become part of the contract, and tooling varies more | Internal calls between services you control |
| Binary serialization | Smaller payloads and faster serialization | Generated clients are required, and payloads are hard to inspect with a browser or curl | High-volume internal traffic where payload size is a measured problem |
Test the workload you actually have. Microsoft’s guidance advises performance and load testing early, against realistic payloads, before a format is locked into a published contract.
Government APIs in the UK
If you build APIs for UK government services, the GOV.UK API technical and data standards are the reference point. They recommend designing, building, and operating APIs consistently so they can be used across platforms and services. The page was last updated 30 September 2026, and its access-control section includes an update on token exchange. These are standards for government APIs. Private providers can borrow the consistency principles, but the standards do not bind them.
What the guidance does not establish
Published API design guidance is prescriptive. It explains what to do and why, but none of the material cited here measures how often breaking changes cause outages, how often retries duplicate writes, or which versioning location produces fewer client failures. Treat any claim that quantifies those outcomes with suspicion unless it names a dataset, a year, and a method. Where this article calls a choice a trade-off, that is a reasoned position, not a measured ranking.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
