API Design: The Contract Between Systems
An API is a long-lived promise. Read what resource-oriented design decides for you and where the contract becomes expensive.
An API is a contract with a long lifetime and an unusual property: the other party does not have to read your code to use it, and cannot be relied on to adapt when you change it. That makes design decisions about naming, versioning, and error behaviour more consequential than similar decisions inside a single program.
Direct answer: Good API design makes the contract legible and boring: resources with consistent names, a small set of standard methods, predictable errors, and a versioning policy that says what may change. Google's published design guidance is resource-oriented, with dedicated rules for resource names, standard methods (Get, List, Create, Update, Delete), custom methods, and versioning. The point of the convention is not aesthetics — it is that a client can predict the shape of an endpoint it has never seen, which is what makes an API cheap to use and safe to evolve.

Why resource-oriented design won
The dominant convention treats an API as a collection of resources — named things with state — manipulated by a small set of methods.
Google's guidance points to specific AIPs for each part: resource-oriented design, resource names, standard methods, custom methods, versioning, and backward compatibility. The existence of separate, numbered rules for each of these is itself the lesson: the surface of an API has many independent decisions, and a convention is a way of making them consistently rather than freshly each time.
The benefit to a client is predictability. If GET /projects/123 returns a project, a client can reasonably expect GET /projects/123/tasks to return its tasks, and DELETE /projects/123 to remove it. That expectation reduces the documentation burden and the chance of a subtle mistake — which is why consistency is worth more in an API than novelty.
Custom methods are the escape hatch, and their existence is a warning. When an operation does not fit Create, Read, Update, or Delete, it may need a custom method, and each one is an exception a client must learn. A proliferation of custom methods usually means the resource model is wrong.
The contract includes failure
A large share of API design is deciding what happens when things go wrong, and 429 Too Many Requests is a good example. RFC 6585 defines it for a client that has sent too many requests in a given time. A response may include Retry-After to indicate how long to wait — RFC 9110 defines its value as an HTTP date or a non-negative delay in seconds — and the status code itself does not disclose whether the limit applies per account, per IP, or across a service.
A client that receives 429 and does not know the scope of the limit cannot implement a sensible backoff, and a team that changes the limit silently can break clients that were relying on it. The contract has to say which dimension is limited and what the recommended behaviour is, or the status code is only half a signal.
The same applies to error bodies, pagination, and the meaning of a partially successful response. None of these is interesting when everything works, and all of them are what a client integrator actually has to code against.
Security is part of the surface
OWASP's API Security Top 10 catalogues the failures that recur in practice, and several are design failures rather than implementation bugs. API1:2023 is broken object-level authorization — the system lets a user access an object they should not, because the API never checked. API3:2023 combines excessive data exposure and mass assignment, and OWASP describes the root cause as "the lack of or improper authorization validation at the object property level". API4:2023 is unrestricted resource consumption, with the note that satisfying API calls requires "network bandwidth, CPU, memory, and storage".
Each of these is a decision about what the API exposes, and each has to be made at design time. Adding authorization after endpoints exist is possible, but it tends to produce inconsistent checks and gaps, because the surface was not designed around a single model of who may see what.
Versioning and the cost of change
The hardest property of an API contract is that clients keep using old versions after you would like them to stop.
A versioning policy is therefore not a formality; it is the statement of how long you will support a promise and what counts as breaking it.
Google's guidance has separate rules for versioning and backward compatibility, which is the right distinction: adding a field may be compatible for most clients and breaking for one that rejects unknown fields; renaming a field is breaking for everyone. A policy that says "we avoid breaking changes" is not a policy until it says which changes count.
Prices, URLs, and schemas all age. The way you retire a version — deprecation notices, overlapping support, a documented removal date — is part of the contract, and clients will judge the API by it.
A design checklist
- Model the resources before defining endpoints, and keep custom methods rare.
- Use consistent names and standard methods so a client can predict an unseen endpoint.
- Specify the failure contract — status codes, error bodies, and rate-limit scope with recommended backoff.
- Decide authorisation at the object and property level, guided by the OWASP categories.
- Write the versioning and backward-compatibility policy, including what counts as breaking and how long support lasts.
- Make the contract testable with a small set of example requests and responses, including failures.
- Change it deliberately. A new field, a new limit, or a new error shape is a contract change even if the code change is small.
For theHTTP semantics behind status codes, see HTTP 429 Too Many Requests; for the low-level protocol, see Safe and Idempotent HTTP Methods.
A worked example
The following is hypothetical and illustrative. A hypothetical scheduling service is exposing a new API to external partners, and the team is reviewing the contract before launch. Three checks decide. First, is the resource model right? Endpoints are named as resources with standard Get, List, Create, Update, and Delete methods, following the Google API Design Guide, so a partner can predict an unseen path and custom methods stay rare. Second, is the failure contract specified? For 429 Too Many Requests the team states whether the limit is per account or per service and gives a Retry-After value in seconds or an HTTP date as RFC 9110 defines; without that scope, a client cannot implement sensible backoff. Third, is authorisation decided at the object and property level? Guided by the OWASP API Security categories, the design checks each object and field before any endpoint ships. The outcome is bounded: a written versioning policy defines what counts as breaking, and a small set of example requests and responses, including failures, becomes the test the contract is held to.
A counterargument
A critic could push back that the article treats Google's resource-oriented convention as settled - "why resource-oriented design won" - when the Google API Design Guide is one company's published preference, not neutral evidence that the abstraction is universally superior. The cited authorities answer different questions: RFC 9110 defines what a 429 means, OWASP catalogues recurring failures, and neither establishes that a resource model fits every domain. The article itself concedes that custom methods proliferate when the resource model is wrong, a significant admission that the convention has a boundary. For APIs whose operations are actions rather than stateful things, predictability may be a weaker benefit than the framing suggests.
Saying consistency is worth more than novelty begs the question of which consistency, and who decides it.
References & Further Reading
- Google, 2026. Google API Design Guide — Practical resource naming, pagination, and error-model conventions.
- R. Fielding, M. Nottingham, and J. Reschke, 2022. HTTP Semantics (RFC 9110) — The normative definition of HTTP methods, status codes, and headers.
- OWASP Foundation, 2023. OWASP API Security Top 10 (2023) — Object-level authorisation and excessive data exposure are the two most common API findings.