All writing
  • api design
  • engineering leadership
  • standards
  • staff engineer

How do I write API standards that every team in a large engineering organisation follows?

Write few rules, give each one its reason, check them with a linter in CI, keep people for the calls a tool cannot make, and give every exception an owner and an end date

API standards get followed when there are few of them, a tool checks each one on every pull request, and the reason for each rule sits next to the rule. A document that depends on people remembering it is a suggestion. Put your rules about errors, pagination, versioning, authorization, rate limits and webhooks into a machine-readable API description, lint it in CI (continuous integration, the automated checks that run on every change), and keep people for the decisions a linter cannot make.

I am Ash, a Staff engineer in Toronto. At an AI startup I worked at, I designed the third-party apps platform and the organisation-wide API standards behind it, covering versioning, OAuth 2.0 app authorization with scoped tokens, webhooks and rate limits. Every engineering team builds against them. This article is for you if you have been asked to write API standards for many teams, or wrote them and nobody follows them. I lean on the published guidelines from Zalando, Google and Azure, on Stripe’s writing about versioning and on the RFCs. Where something is my opinion, I say so.

One API change meets four checks. First, the spec is written before the code, with the rules kept in a ruleset. Second, a linter checks naming, errors, scopes and pagination on every pull request. Third, a person reviews new APIs and breaking changes, not every edit. Fourth, the change is published with a changelog, and every exception has an owner and an end date.

Write few rules and give each one its reason

Standardise what costs another team when it varies, and leave the rest to the team that owns the API. An error format that differs from service to service costs every developer who calls them, and the spelling of an internal field name costs almost nobody. Zalando states the aim plainly in its RESTful API guidelines: “Ideally, all Zalando APIs will look like the same author created them.”

Say how binding each rule is. Zalando marks every rule MUST, SHOULD or MAY. The Azure REST API guidelines go further and say what each label costs the team. For a DO or DO NOT rule you contact the review board before you build. For a YOU SHOULD rule you “MUST disclose your reason” in review. In my opinion, if most of your document is MUST, none of it is.

Write the reason beside the rule. Google’s API Improvement Proposals (AIPs) do this, and AIP-158 on pagination and AIP-180 on backwards compatibility both have a Rationale section. People follow a rule when they can see the failure it prevents, and a reviewer can judge an exception by asking whether the reason applies. A Spectral ruleset (Spectral is a linter for API descriptions, more on it below) can carry a documentationUrl that, in the words of its custom rulesets guide, “can help provide users more context on why the ruleset exists and how it should be used”.

What the standard should say

Six topics cover most of what hurts the people who call your APIs. Naming has its own rules, which I wrote out in how to name REST resources, routes and associations.

Versioning and compatibility

The published guides disagree here, so the choice matters less than making one. Google’s AIP-185 says every API “must provide a major version number” that is “included as the first part of the URI path for REST APIs”. Zalando says “we do not use URL versioning” and prefers media types when versions are unavoidable, but first tells teams to avoid new versions. Azure requires an api-version query parameter whose value is a date. Stripe names its versions by date and pins each account to the version that was newest at its first request.

Pick one scheme and write it down. I would write the compatibility rules first, because every version you create is a cost. Stripe says “every new version is more code to understand and maintain”, and AIP-180 gives the reason compatibility matters: “APIs are fundamentally contracts with users”. List what counts as breaking, such as removing or renaming a field, so teams do not argue it case by case.

Authorization with scoped tokens

The rule that pays off most is that every operation names the scope it needs, in the API description. OAuth 2.0 (RFC 6749) says tokens “represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server”. It leaves the scope names to each server and says only that the server “SHOULD document its scope requirements”. So your standard has to add a naming pattern for scopes and a rule that no endpoint is open by accident. Zalando has both, as separate rules.

Errors

Use one error shape across the organisation. RFC 9457 defines problem details so that you can “avoid the need to define new error response formats for HTTP APIs”, and Zalando requires every endpoint to be able to return one. Google takes another route and defines its own error status in AIP-193, which also requires “machine-readable identifiers” in every error. Either works, as long as client code can branch on a stable code and not on the wording of a message.

Pagination

Make every list paginate from the first release. AIP-158 says collections “must provide pagination at the outset”, because adding it later is “a backwards-incompatible change to add pagination to an existing method”. Zalando prefers cursor-based pagination over offset-based. Fix the parameter names once, so a developer who has paged through one API can page through all of them.

Rate limits

Use one status and one way to say when to come back. RFC 6585 defines 429 as the code that “indicates that the user has sent too many requests in a given amount of time” and says the response may carry a Retry-After header. Zalando requires 429 together with headers that describe the limit. State the limit for each app in the documentation, because a client throttled without a number to plan around will retry blindly.

Webhooks

A webhook is part of your API, and the Standard Webhooks specification calls it a sort of “reverse API”. It signs the message ID, the timestamp and the body together, tells receivers to check that the timestamp is within a tolerance to prevent replay attacks, and notes that the ID “is often used as an idempotency key”. The organisation’s rule is one signing scheme and one retry behaviour, so a developer who has built one receiver can build all of them.

Check the rules with tools

Move the rules into a file a machine can read. The OpenAPI specification describes an HTTP API so that people and computers can “discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection”. Zalando makes it a rule: “You must define APIs first, before coding its implementation, using OpenAPI as specification language.”

Once the description lives in the repository, a linter can read it. Spectral is “a flexible JSON/YAML linter for creating automated style guides”, with built-in support for OpenAPI. This is the example rule from its ruleset docs.

rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case and separated with hyphens)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

Google ships the API Linter for its AIPs. The good candidates are rules you can state as a check on the file, such as path casing, a security requirement on every operation and pagination parameters on every list.

Two habits keep the linter from becoming hated, and both are my opinion. Start a new rule at the warn severity (the Spectral docs say severity helps “define the importance of following the rule”) and move it to error once the existing specs pass. And when a reviewer writes the same comment twice, write the rule.

Keep people for what a tool cannot read

A linter can see that a field was removed. It cannot see that a field now means something different, and AIP-180 treats that kind of semantic compatibility as a break of its own. It cannot tell you that an endpoint mirrors a database table when the developer is trying to finish a task. Those calls need a person.

Keep review light, or teams will route around it. Google’s design review FAQ says review exists to ensure “a simple, intuitive, and consistent API experience” and is expected only for APIs that users code directly against. Stripe describes a “lightweight API review process” in which a change is written up in a brief document and sent to a mailing list. I ran design reviews at the startup. My rule of thumb is to review new APIs and breaking changes, and let anything that passes the linter go through without a meeting.

Give exceptions an owner and an end date

Every standard needs a way out, or teams leave without telling you. Azure’s labels build one in, because an exception needs a conversation before the build or a stated reason in review. Zalando covers age. Its guidelines say existing APIs need not change when the rules do, new APIs follow the current rules, and an API that becomes public is re-reviewed.

I would log each exception with the rule it waives, the reason, the owner and an end date. A rule that many teams ask to waive is probably wrong, and the log is how you find out.

What a third-party apps platform changes

Outside developers cannot read your code, cannot join your design review and upgrade when it suits them. The bar goes up in three ways.

Compatibility becomes a promise. Azure lists it as a goal: “Customer workloads must never break due to a service change”. Zalando requires the owner of an API with external partners to agree a deprecation period with them, and to get their consent before a shutdown. Documentation becomes part of the product, and Stripe says its API changelog “is programmatically generated”. And security has to be built in, because you do not know the client, so scopes, signed webhooks and per-app rate limits are the standard and not options.

In my opinion, one standard for internal and external APIs is easier to keep than two.

What this costs, and what I would not do

A ruleset is a product with users. Someone has to maintain it and fix its false alarms, and every false alarm costs trust. Teams with older APIs face a backlog, and a team running a fast experiment will feel the rules as friction. Give the ruleset an owner, or it will rot.

I would rule out three options. A long handbook with no checks, because nobody reads it twice. A board that approves every change, because it turns into a queue. And copying one published guide whole, because the guides above disagree with each other. Name the guide you follow and write down your differences.

How to tell it works

I would watch five signals. They are the share of APIs whose spec is in the repository and passes lint, the exceptions for each rule, the breaking changes found after release, the time a new API waits for a review answer, and whether a new team can build a compliant API from a starter spec without asking you. If the first rises and the third falls, the standards are being followed.

A plan for the first month

  1. List the client complaints and incidents your APIs caused, and choose the eight to ten rules that would have prevented the most.
  2. Write each rule with its label, its reason and a good and a bad example.
  3. Turn them into a ruleset and run it on your existing specs in warning mode. Fix any rule that fails everything.
  4. Publish a starter spec that already passes. It is the same idea as the paved road in how to get engineering teams to adopt an internal developer platform.
  5. Make the high-signal rules blocking, start the exception log, and schedule review for new APIs and breaking changes only.
  6. Read the exception log a month later and change the rules it points at.

A standard is finished when a new team can follow it without asking you.

Frequently asked questions

Which published API guidelines should I base mine on?

Start from one and write down your differences. Zalando’s guidelines are a concrete MUST, SHOULD and MAY checklist that is easy to adapt, Google’s AIPs explain their reasons in depth and Azure’s guidelines show how to run exceptions. Add RFC 9457 for errors, RFC 6749 for authorization and OpenAPI as the contract format.

Should I enforce API standards with a linter or with design reviews?

Use both, for different jobs. A linter checks anything you can state as a rule on the API description, on every change. People review what it cannot read, such as the shape of a new API and any change that could break a client.

Should the version go in the URL?

Choose once. Google puts a major version at the start of the path, Zalando prefers media types, and Azure and Stripe use dates.

What do I do with APIs that already break the new rules?

Leave them alone until they change, and hold new APIs to the current rules, which is also Zalando’s line. Log the gaps as exceptions with an end date so they stay visible.

Do webhooks need the same standards as the API?

Yes, because a webhook is part of your API. Give them one payload shape, one signing scheme with a timestamp check, an event ID for skipping duplicates, and documented retries.