# API Design Best Practices: The Complete Guide

URL: https://www.devopsness.com/blog/api-design-best-practices
Author: Kiril Urbonas
Published: 2026-08-12
Updated: 2026-10-31
Categories: DevOps
Tags: API Design, REST, gRPC, GraphQL, Backend

Summary: 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.

---
# API Design Best Practices: The Complete Guide

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]
> 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](/blog/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](/blog/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](/blog/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](/blog/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](/blog/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](/blog/api-versioning-strategies).

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

```yaml
# 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](/blog/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](/blog/caching-patterns-read-write-through-cache-aside).

## 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

- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)
- [IETF draft: The Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
- [OpenAPI Specification (latest)](https://spec.openapis.org/oas/latest.html)

