API Design Best Practices: The Complete Guide
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.
On this page
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.
| REST | gRPC | GraphQL | |
|---|---|---|---|
| Best for | Public/web APIs | Internal service-to-service | Clients needing flexible, exact-shape queries |
| Payload | JSON, human-readable | Protobuf, binary | JSON |
| Caching | HTTP caching works natively | Needs application-level caching | Needs application-level caching |
| Browser-friendly | Yes | No (needs grpc-web/gateway) | Yes |
| Learning curve | Low | Moderate (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:
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:
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.
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:
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: 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 see | Usually means | What to do |
|---|---|---|
200 OK with {"error": ...} in the body | Error hidden in a success code | Send the real 4xx/5xx with a problem+json body |
415 Unsupported Media Type | Client omitted Content-Type: application/json | Document the required media type in OpenAPI |
409 Conflict on a retried POST | Same idempotency key, original still in flight | Client backs off and retries with the same key |
412 Precondition Failed | If-Match ETag is stale; someone else updated first | Client refetches, merges, retries |
429 Too Many Requests with no Retry-After | Client has to guess backoff and hammers you | Always include Retry-After and RateLimit fields |
500 on bad input | Validation missing, exception escaped | Validate 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
Cite this article
Kiril Urbonas (2026). API Design Best Practices: The Complete Guide. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/api-design-best-practices
[API Design Best Practices: The Complete Guide](https://www.devopsness.com/blog/api-design-best-practices) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from DevOps
Explore more articles in this category
GitHub's September 13 Outage: One Cleanup Job, Many Services
A background cleanup job saturated a shared database behind GitHub, and the safeguard pacing it watched only replica lag. Throttle on more than one signal.
Common Git Errors and How to Fix Them (2026 Guide)
Rejected pushes, local changes that would be overwritten, merge conflicts, detached HEAD, unrelated histories, publickey denials, and oversized files. What each message means and the safe fix.
12 Scenario-Based DevOps Interview Questions (With Answers)
Senior DevOps interviews have moved from definitions to "it's 2 a.m. and this is broken". Twelve real scenarios, what the interviewer is testing, and the answer that gets the offer.
You might have missed
Evergreen posts worth revisiting.