API design best practices for APIs other teams will enjoy using

API design best practices are the conventions that make an interface predictable for the people who call it: how resources are named, how HTTP methods and status codes are used, how errors, lists, versions and security work. None of them is clever on its own. Their value comes from being applied the same way across every endpoint.

A useful test of an API is how far a new developer gets with only the documentation. If they can authenticate, fetch a list, create a record and understand a failure without asking anyone, the design is doing its job. If they need a call with your team for each step, the API is costing both sides time on every integration.

This guide focuses on HTTP APIs in the REST style, which most business systems use for integrations. If you are deciding whether to build an integration at all or connect existing tools, start with our build vs buy software guide.

Design the contract first because it is far cheaper to change a document than a deployed API with live clients. In a design-first process, the team writes the endpoints, fields and error responses in the OpenAPI Specification (opens in a new tab), shares it with the people who will consume it, and only then starts building.

An OpenAPI file is machine-readable, so it does more than describe. It can generate interactive documentation, mock servers that client teams code against while the real API is built, request validation and client libraries. The specification is maintained by the OpenAPI Initiative, and version 3.2 is the current release at the time of writing.

Name resources as plural nouns and let HTTP methods carry the verbs: /invoices, /invoices/{id}, /customers/{id}/orders. Avoid action names like /getInvoice or /createOrder, which duplicate what the method already says and drift into inconsistency as the API grows.

Use each method for the meaning defined in HTTP semantics, published by the IETF as RFC 9110. That standard defines which methods are safe (they change nothing) and which are idempotent (repeating them has the same effect as sending them once). Clients, proxies and caches rely on those meanings, so breaking them causes subtle bugs.

Pick one style for field names, such as camelCase or snake_case, and use it everywhere. Send dates and times in ISO 8601 format with a time zone, and money as an amount plus a currency code rather than a bare number.

Report errors with the correct HTTP status code and one consistent, machine-readable body. The IETF standard for that body is RFC 9457, Problem Details for HTTP APIs (opens in a new tab), which replaced RFC 7807. It defines fields such as type, title, status and detail, and lets you add your own, for example a list of invalid fields.

Good error messages tell the caller what to fix. "Validation failed" forces a support ticket. "dueDate must be on or after issueDate" lets the developer fix the request in a minute. Never return internal details such as stack traces or SQL, which help attackers more than they help clients.

• 400 Bad Request: the request is malformed or fails validation.
• 401 Unauthorized: no valid credentials were sent.
• 403 Forbidden: the caller is known but not allowed to do this.
• 404 Not Found: the resource does not exist, or the caller may not know it exists.
• 409 Conflict or 412 Precondition Failed: the record changed since the caller last read it.
• 429 Too Many Requests: the caller hit a rate limit and should wait before retrying.
• 5xx: something failed on the server; the client may retry later.

Paginate every list endpoint from the first release, even if the list is short today, because adding pagination later breaks clients that expect everything in one response. Return a page of results plus a token for the next page, and let the client choose a page size within a limit you set.

Cursor or token-based pagination is usually safer than page numbers for data that changes, since new records do not shift items between pages. Google's API design guidance, AIP-158 on pagination (opens in a new tab), describes this pattern with a page size and an opaque page token. Filtering and sorting should use clear query parameters, such as status=open or sort=-createdAt, documented with examples.

Decide your versioning rule before the first release, and make additive changes the norm. Adding a new optional field or a new endpoint should not break anyone, provided clients are told to ignore fields they do not recognize. Removing a field, renaming it or changing its meaning is a breaking change and needs a new major version.

The simplest and most visible approach is a major version in the path, such as /v1/ and /v2/. Whatever you choose, publish a deprecation policy: how long an old version keeps working after a new one launches, and how clients will be warned. Then keep that promise, because trust in an API is mostly trust that it will not change under you.

Versioning matters most when an API sits in front of an older system that is being replaced. In an incremental legacy modernization project, a stable API lets new code replace legacy parts behind it while client integrations stay untouched.

Security belongs in the contract, not in a review after launch. The OWASP API Security Top 10 (2023 edition) lists the most common API weaknesses, and the first on the list, broken object level authorization, is a design issue: the API returns a record because the caller knows its ID, without checking that the caller may see it.

Design each endpoint with three questions in mind. Who may call it? Which records may they touch? Which fields may they read or change? Write the answers into the contract and test them, because many serious API incidents come from a missing check on one of these, not from broken encryption.

• Authorize every request at the object level, not just at sign-in.
• Return only the fields the caller needs; never send whole database rows.
• Reject unknown or read-only fields on writes, so callers cannot set roles or prices.
• Limit request sizes, page sizes and call rates to prevent resource exhaustion.
• Use HTTPS everywhere and short-lived tokens, such as OAuth 2.0 access tokens.
• Keep an inventory of every API version and environment, and retire old ones.

Make writes safe to retry, and tell clients how much traffic they may send. Networks fail mid-request, so a client that never received a response will often send it again. If that request was "create a payment", a naive API creates two.

The common fix is an idempotency key: the client sends a unique value with each create request, and the server returns the original result if the same key arrives twice. For updates, use ETags with the If-Match header so that two people editing one record cannot silently overwrite each other. For load, return 429 with a Retry-After header when a client exceeds its limit, and document the limits publicly.

These API design best practices are where our API development and third-party integrations work spends much of its testing time, because they decide whether an integration behaves well on a bad network day.

Run through these API design best practices before any API goes live to a partner or another team. Each item is quick to verify against the OpenAPI contract and a test environment.

• The OpenAPI contract is complete, reviewed by a consumer and matches the running API.
• Every endpoint has an example request and response in the documentation.
• Resource names, field style and date formats are consistent across endpoints.
• Errors use correct status codes and one Problem Details format.
• Every list is paginated and has a maximum page size.
• The versioning and deprecation policy is written and published.
• Object, field and function level authorization are tested for each role.
• Create requests accept an idempotency key; updates support conditional requests.
• Rate limits are enforced, documented and signaled with 429 and Retry-After.
• Logs record who called what, without storing secrets or personal data unnecessarily.