lockstep
4 min readNaman Jain

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.

MethodHTTPPath
ListGET/v1/projects
GetGET/v1/projects/{id}
CreatePOST/v1/projects
UpdatePATCH/v1/projects/{id}
DeleteDELETE/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_token in the request and next_page_token in the response
  • Page sizes above the maximum are coerced down, not rejected
  • A negative page_size is an INVALID_ARGUMENT error

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

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