Skip to main content
API Design Best Practices: The Complete Guide

API Design Best Practices: The Complete Guide

KU
· Founder & Chief Editor
• 8 min read•Updated •

A good API is a promise you can keep for years. This is the map: the conventions, the protocols, and the details that make an API pleasant to use and safe to change.

Key takeaways

  • Design APIs around the domain your consumers care about, not your database tables.
  • Default to REST for public APIs, gRPC between services and GraphQL for flexible client queries.
  • Treat versioning, cursor pagination, idempotency keys, rate-limit headers and RFC 9457 problem-details errors as part of the contract from day one, documented in OpenAPI.

Good API design means modeling the consumer's domain rather than your tables, then making the contract boringly predictable: consistent resource names and status codes, cursor pagination, idempotent writes, explicit rate limits, structured errors in RFC 9457 format, and an OpenAPI spec as the source of truth. Default to REST publicly, gRPC between services, GraphQL when clients need flexible queries.

Verified against

OpenAPI Specification 3.2.1 (10 September 2026), RFC 9110 HTTP Semantics, RFC 9457 Problem Details, IETF drafts idempotency-key-header-08 and ratelimit-headers-11, against spec.openapis.org, rfc-editor.org and datatracker.ietf.org. Checked October 2026.

An API is a contract you have to keep for years while everything behind it changes. An API that mirrors your tables leaks your internals and traps you; one that models what the client cares about stays stable while you refactor freely. Everything below is in service of that.

Pick the protocol by who is calling

  • REST is the default for public and web APIs: resource-oriented, cacheable, universally understood. The conventions are in REST API best practices.
  • gRPC wins for internal service-to-service calls that need speed and strict contracts. The trade-offs are in gRPC vs REST.
  • GraphQL shines when clients need exact-shape queries over a graph of data. When it beats REST, and when it doesn't, is in GraphQL vs REST.

Most systems end up with more than one: REST or GraphQL at the edge, gRPC between services.

RESTgRPCGraphQL
Best forPublic/web APIsInternal service-to-serviceClients needing flexible, exact-shape queries
PayloadJSON, human-readableProtobuf, binaryJSON
CachingHTTP caching works nativelyNeeds application-level cachingNeeds application-level caching
Browser-friendlyYesNo (needs grpc-web/gateway)Yes
Learning curveLowModerate (schema, codegen)Moderate (resolvers, N+1 pitfalls)

Get the HTTP semantics right first

Most API bugs that reach clients are semantic, not syntactic. RFC 9110 defines GET, HEAD, OPTIONS and TRACE as safe, and PUT, DELETE plus the safe methods as idempotent. POST is neither. That has consequences: proxies and client libraries may retry idempotent requests on a dropped connection, so a GET that mutates state or a PUT that appends will eventually double-apply.

Use nouns for resources and methods for actions (POST /orders, not POST /createOrder). Be consistent everywhere about casing, ISO 8601 timestamps and ID formats. Validate input strictly and reject unknown fields rather than silently ignoring them, because silent ignoring hides client typos until production.

Make errors machine-readable with RFC 9457

Clients branch on errors, so give them something to branch on. RFC 9457 (July 2023, obsoleting RFC 7807) defines application/problem+json with type, title, status, detail and instance, plus your own extension members:

Terminal
curl -s -i -X POST https://api.example.com/v1/orders \
    -H 'Content-Type: application/json' -d '{"sku":"A-1","qty":0}'
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation",
  "title": "Request body failed validation",
  "status": 422,
  "detail": "qty must be at least 1",
  "instance": "/v1/orders",
  "errors": [{ "field": "qty", "code": "min", "min": 1 }]
}

The type URI is the stable contract; detail is for humans and may change. Clients must ignore extension members they do not recognize, so adding errors later is non-breaking.

Make writes safe to retry

Networks drop responses after the server has committed the write. Without protection, the client's retry creates a second order. The IETF Idempotency-Key header draft (revision 08, updated 22 October 2026, still not an RFC) standardizes the pattern Stripe-style APIs already use:

Terminal
curl -s -i -X POST https://api.example.com/v1/payments \
    -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
    -H 'Content-Type: application/json' -d '{"amount":5000,"currency":"EUR"}'

The server stores the key with the request fingerprint and the response, and replays the stored response on a repeat. The draft recommends 400 when a required key is missing, 422 when a key is reused with a different payload, and 409 when a retry arrives while the original is still processing. Note that the value is a quoted Structured Fields string.

Bound every list and publish your limits

Never return an unbounded collection. Use cursor pagination for anything that grows; offset pagination skips or repeats rows when data changes between pages, and gets slower deep into the set. Full trade-offs are in API pagination.

Terminal
curl -s 'https://api.example.com/v1/orders?limit=50&cursor=eyJpZCI6MTIzNH0'
{ "data": [ ... ], "next_cursor": "eyJpZCI6MTI4NH0" }

Keep the cursor opaque so you can change its encoding without breaking clients.

For limits, tell clients their quota instead of letting them discover it through 429 Too Many Requests (defined in RFC 6585). The IETF RateLimit headers draft (revision 11, May 2026, still a draft) defines two fields:

code
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=50;t=30

That reads as 100 requests per 60-second window, 50 remaining, window resets in 30 seconds. Because it is a draft, many APIs still send the older X-RateLimit-* headers; pick one, document it, and always send Retry-After with a 429. Algorithms and placement are in API rate limiting.

Version deliberately, and make the spec the source of truth

Additive changes (new optional fields, new endpoints) should never need a version bump; that is why clients must ignore unknown fields. Breaking changes (removing or renaming fields, tightening validation, changing types) get a new version and a published migration window. Strategies are compared in API versioning strategies.

Write the contract in OpenAPI before the handlers, then lint it and generate clients and server stubs from it:

openapi.yaml
openapi: 3.2.1
info: { title: Orders API, version: 1.4.0 }
paths:
  /v1/orders:
    post:
      operationId: createOrder
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string }
      responses:
        "201": { description: Created }
        "422":
          description: Validation failed
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }

The info.version is your API's version; the top-level openapi field is the spec version. Authentication, authorization and the OWASP API risks are in API security best practices.

Status codes clients misread, and what to send instead

Response clients seeUsually meansWhat to do
200 OK with {"error": ...} in the bodyError hidden in a success codeSend the real 4xx/5xx with a problem+json body
415 Unsupported Media TypeClient omitted Content-Type: application/jsonDocument the required media type in OpenAPI
409 Conflict on a retried POSTSame idempotency key, original still in flightClient backs off and retries with the same key
412 Precondition FailedIf-Match ETag is stale; someone else updated firstClient refetches, merges, retries
429 Too Many Requests with no Retry-AfterClient has to guess backoff and hammers youAlways include Retry-After and RateLimit fields
500 on bad inputValidation missing, exception escapedValidate at the edge, return 400 or 422

Where this breaks

These defaults assume a public or multi-team API with clients you do not control. For one backend talking to one frontend you deploy together, strict versioning and full OpenAPI tooling can be overhead, and a typed RPC layer may serve you better. OpenAPI 3.2 is recent, so check that your generators and gateways support it before bumping; many still target 3.0 or 3.1. The idempotency and RateLimit headers are drafts and may still change, so wrap them behind your own docs rather than promising RFC behavior. And for read-heavy APIs, HTTP caching often matters more than any of the above; see caching patterns.

Questions people ask

What are the most important API design best practices?

Model the consumer's domain instead of your database, use HTTP methods and status codes as RFC 9110 defines them, and keep naming and formats consistent. Bound every list with cursor pagination, make writes safe to retry with idempotency keys, return RFC 9457 problem-details errors, publish rate limits, and keep an OpenAPI spec as the contract that code and docs are generated from.

Should I use REST, gRPC or GraphQL?

Use REST for public and browser-facing APIs, because it is cacheable and every client understands it. Use gRPC for internal service-to-service calls where binary payloads and generated, strictly typed clients pay off. Use GraphQL when many clients need different shapes of the same data. Most mature systems run REST or GraphQL at the edge and gRPC behind it.

What is the standard format for API error responses?

RFC 9457, Problem Details for HTTP APIs, which replaced RFC 7807 in July 2023. Responses use the application/problem+json media type with type, title, status, detail and instance members, and you can add extension fields such as a list of invalid fields. Clients key off the type URI, which stays stable, while detail is free text for humans.

The call we'd make

Model the domain, not the schema. Default to REST for public APIs, gRPC between services, GraphQL only when clients really need query flexibility. Ship idempotency keys, cursor pagination, rate-limit headers and problem-details errors in version one, because retrofitting them is a breaking change. Write the OpenAPI spec first and keep it honest; each linked guide goes deep on one of these decisions.

Sources

Explore topics:DevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). API Design Best Practices: The Complete Guide. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/api-design-best-practices

Markdown

[API Design Best Practices: The Complete Guide](https://www.devopsness.com/blog/api-design-best-practices) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

608 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.