API design best practices: 8 rules from Google's API guidelines
API design best practices from Google's AIPs: resource-oriented design, naming, standard methods, pagination from day one, actionable errors, and compatibility.
A team ships three new endpoints in a month. One paginates with page and limit, one with offset, and one returns everything. Errors come back as {"error": "bad"} in one service and HTTP 200 with success: false in another. Every client integrates three times.
None of these are hard problems. They're decisions nobody wrote down. This guide covers the most useful rules from Google's API Improvement Proposals, checked on 16 November 2026, which many teams use as a starting point.
1. Design around resources
Google's AIP-121 describes resource-oriented design: an API built from individually named resources (nouns) and methods (verbs), modeled as a hierarchy where each node is a resource or a collection of the same type. It borrows many principles from REST.
Start by listing the resources, their relationships, their schemas, and the methods each needs, before writing any endpoint.
2. Prefer standard methods
Use the standard set wherever it fits: Get, List, Create, Update, Delete. Custom methods are for what doesn't fit, such as :cancel or :archive. A client that knows one resource then knows how to use them all.
| Method | HTTP | Path |
|---|---|---|
| List | GET | /v1/projects |
| Get | GET | /v1/projects/{id} |
| Create | POST | /v1/projects |
| Update | PATCH | /v1/projects/{id} |
| Delete | DELETE | /v1/projects/{id} |
3. Name consistently
Resource names should be predictable: plural collection names, stable IDs, the same field name for the same concept everywhere. created_at in one resource and creationDate in another costs every client a lookup. See AIP-122 for resource names.
4. Paginate every list, from day one
AIP-158 is direct: list methods must provide pagination at the outset, because adding it later is a backward-incompatible change. Its pattern:
- A request
page_size, optional, with a documented default - An opaque
page_tokenin the request andnext_page_tokenin the response - Page sizes above the maximum are coerced down, not rejected
- A negative
page_sizeis anINVALID_ARGUMENTerror
Opaque tokens let you change how pagination works internally without breaking clients.
5. Make errors actionable
AIP-193 says services must return a standard status with canonical error codes, so clients can handle errors in one place. Messages should help a reasonably technical user understand and fix the problem, not assume expertise in your API. Keep them brief; put extra information in a details field or a link.
{
"error": {
"code": 400,
"status": "INVALID_ARGUMENT",
"message": "page_size must be between 1 and 1000.",
"details": [{ "field": "page_size", "docs": "https://example.com/docs/pagination" }]
}
}
6. Never break existing clients
AIP-180 says existing client code must not break when a service updates to a new minor or patch release, across three kinds of compatibility: source, wire, and semantic. Among its rules:
- Don't add required fields to existing requests or resources.
- New client-populated fields need a default behavior that matches the old behavior.
- Fields the server populated before must keep being populated.
- Don't change what an existing field means.
For anything that must break, ship a new major version and keep the old one running for a stated period.
7. Version deliberately
Pick one versioning scheme and use it everywhere. Major version in the path, /v1/, is common and easy for clients to see. Write down how long old versions are supported.
8. Write the rules down
Every rule above is a team decision: pagination style, error format, versioning, deprecation period. Written as ADRs or an API style guide, they make every new endpoint consistent. Left unwritten, each engineer, and each AI coding agent, copies whichever existing endpoint it finds first.
Where Lockstep fits
API conventions are exactly the kind of decision agents get wrong when they only see the code. Lockstep captures decisions from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply, so an agent adding an endpoint uses cursor pagination because the team decided it, not offset because the oldest endpoint does.
See how it works.
Sources checked 16 November 2026
- https://google.aip.dev/121
- https://google.aip.dev/122
- https://google.aip.dev/158
- https://google.aip.dev/180
- https://google.aip.dev/193
Related reading
For proposing an API change, see the engineering RFC template. For designing it in depth, see the technical design document template. For announcing deprecations, see the release notes template.
Frequently asked questions
- What are the most important API design best practices?
- Model the API as resources and standard methods, name things consistently, paginate list methods from the start, return standard error codes with actionable messages, and keep changes backward compatible. Google's API Improvement Proposals cover each of these in detail.
- What is resource-oriented design?
- A pattern described in Google's AIP-121 where an API is built from individually named resources, arranged in a hierarchy of collections, with a small set of standard methods such as Get, List, Create, Update, and Delete. It borrows many principles from REST.
- Why paginate list endpoints from the start?
- Google's AIP-158 says list methods must provide pagination at the outset, because adding it later is a backward-incompatible change: clients that expect every result in one response would silently get only the first page.
- What counts as a breaking API change?
- Per Google's AIP-180, changes that break source, wire, or semantic compatibility for existing clients, such as adding a new required field to a request, removing or renaming fields, or changing what an existing field means or how it behaves.
- How should API errors be designed?
- Google's AIP-193 says to return a standard status with canonical error codes, and messages that help a reasonably technical user understand and resolve the issue, briefly, with extra information in a details field or a link.
Keep reading