Skip to content
Novandri.

API Design: REST, GraphQL, gRPC, API Gateway, Rate Limiting

These are choices about where complexity lives. Read what each style buys, what the gateway actually does, and how to make retries safe.

Rachmadwipa Novandri8 min read

Style debates about APIs are usually settled by fashion rather than analysis, and the reason is that the question is framed wrongly. REST, GraphQL, and gRPC are not competing answers to one problem; they place the complexity in different parts of the system. Which one is right depends on who calls the API, how often, over what network, and who has to change it when the business changes.

Direct answer: REST organises an API as resources addressed by URLs with standard methods; the durable-contract side of that choice is covered in API Design: The Contract Between Systems. GraphQL lets clients request the exact shape of the response, moving query complexity to the server. gRPC uses a schema and binary encoding, buying efficiency and strong typing at the cost of browser and human readability. An API gateway handles cross-cutting concerns — authentication, rate limiting, routing — and safe retries require idempotency, which Stripe implements with client-generated keys: "The API supports idempotency for safely retrying requests without accidentally performing the same operation twice."

A four-step flow: REST resources, GraphQL client-shaped queries, gRPC schema and wire, then gateway auth and limits.
Conceptual: the style decides who absorbs the complexity. Rate limiting is a policy decision, not a technical setting.

REST is the baseline

REST's advantage is not performance. It is that a client can predict the shape of an endpoint it has never seen, which is why it remains the default for public APIs. That predictability comes from a resource model and consistent standard methods — the subject of API Design: The Contract Between Systems, which covers resource naming, the failure contract, and versioning in depth.

What matters for the style decision here is narrower: REST maps onto HTTP semantics, so it inherits HTTP's caching, status codes, and tooling. That makes it a strong default when clients are external and varied. The alternative styles are best understood as answers to cases where that baseline does not fit.

GraphQL moves the work

GraphQL lets a client specify which fields it wants, and the server resolves exactly that shape — the query language and type system are defined in the GraphQL specification. The benefit is real for clients with varied needs — a mobile app and a reporting tool can ask for different fields from the same endpoint — and it reduces the number of round trips needed to assemble a screen.

The costs are also real. Query complexity moves to the server, which now has to parse and authorise arbitrary selections and may need to defend against expensive queries. Caching is harder because responses are request-specific, and the familiar HTTP caching model applies less directly.

A GraphQL endpoint that becomes the single entry point for every client can turn into a distributed monolith with a schema that is difficult to evolve.

The question to ask is whether clients genuinely need different shapes. If they all need the same data, the extra machinery buys little.

gRPC is about the contract and the wire

gRPC uses a schema to define services and messages, and a binary encoding for transport, as described in the official gRPC documentation. The benefits are strong typing, generated clients, and efficient serialisation — particularly valuable for service-to-service communication over a controlled network.

The costs are that the protocol is not human-readable in the way JSON over HTTP is, browser support requires additional machinery, and debugging needs appropriate tools. It is a good fit for internal services where both sides are owned by the same organisation and the schema can be versioned deliberately. It is usually the wrong fit for a public API whose clients you do not control.

What the gateway actually does

An API gateway terminates client connections and routes them to backend services, but its value is the cross-cutting work it performs in one place: authentication, authorisation checks, rate limiting, request validation, logging, and sometimes response transformation.

Doing these once at the boundary is better than reimplementing them in every service, and it is also where a new class of failure appears: the gateway becomes a single point of failure and a bottleneck, and its configuration becomes a critical part of the system. A gateway that enforces a limit based on a client identifier it cannot reliably determine will rate-limit the wrong party, which is why the identity dimension has to be explicit.

Rate limiting itself is a policy decision, not a technical setting.

OWASP's API Security Top 10 treats unrestricted resource consumption as a design failure, and the economics behind the limit belong in the failure contract described in API Design: The Contract Between Systems. A limit that ignores per-request cost can be economically wrong even when it is technically correct.

Idempotency is what makes retries safe

Any client that retries a request over an unreliable network faces a question: did the first attempt succeed? If the operation created an order, retrying it might create two.

Stripe's implementation is the clearest published example. "The API supports idempotency for safely retrying requests without accidentally performing the same operation twice", and the mechanism is a client-generated key: "A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request." For API v1, "Stripe saves the status code and body of the first request made with a given idempotency key after endpoint execution begins" — so a retry returns the original result rather than executing again. Keys are "up to 255 characters", and the guidance explicitly says to "avoid using sensitive data (for example, email addresses or personal identifiers) as idempotency keys".

255maximum length in characters of a Stripe idempotency keyStripe, Idempotent requests

A worked versioning problem

The policy side of versioning is covered in API Design: The Contract Between Systems. This example shows what such a policy actually has to decide.

Suppose an API returns a customer object with a name field that clients display. The business now needs separate given and family names. Three changes are possible, and they have very different consequences:

  • Add given_name and family_name while keeping name. Older clients work unchanged; new clients use the structured fields. This is backward-compatible, and Google's design guide treats adding fields as a compatibility question precisely because some clients reject unknown fields. A client that strictly validates the response will still break, so "compatible" is a property of the client population, not of the server change alone.
  • Rename name to full_name. Every client that reads name now receives nothing. This is a breaking change regardless of how carefully it is announced.
  • Change the meaning of name to mean only the given name. Nothing about the schema changed, so no versioning policy catches it, and every client silently displays the wrong thing. This is the most dangerous of the three because it is invisible to contract testing.

The lesson is that a versioning policy has to cover semantics as well as structure. A change can violate backward compatibility without being a version bump at all, which is why the policy must define ownership of field meanings.

A practical policy therefore states: which changes are permitted without a version bump, how long previous versions are supported, what notice clients receive, and how a deprecated version is removed. It should also define ownership of field meanings, because the third case above cannot be solved by a version number at all.

A decision sequence

  1. Choose the style by who calls the API and what they vary, not by popularity.
  2. Define the resource model or schema first, and keep custom operations rare.
  3. Make the failure contract explicit — status codes, error bodies, and the dimension used for rate limits.
  4. Implement idempotency for any non-idempotent operation, with a client-generated key and a documented retention window.
  5. Put cross-cutting concerns at the gateway, with an explicit identity rule for limits.
  6. Write the versioning and compatibility policy, including what counts as a breaking change.
  7. Test the failure paths — timeouts, retries, limit breaches — as carefully as the happy path.

For the protocol underpinnings, see Safe and Idempotent HTTP Methods and HTTP 429 Too Many Requests. For the shared foundations — resource naming, the failure contract, HTTP semantics, and the OWASP API Security Top 10 — see API Design: The Contract Between Systems, which is the canonical home for that material.

A counterargument

A reasonable critic could argue that the article's "it depends where the complexity lives" framing is so accommodating that it refuses to recommend anything - every style is a reasonable answer to some situation, leaving a decision sequence rather than a real trade-off. The GraphQL specification and gRPC documentation are cited for what each style is, but the warnings about query complexity and non-human-readable wire formats are asserted rather than evidenced by those sources; a specification describes capabilities, not failure rates. Stripe's idempotency example is a single, well-resourced implementation - 255-character keys and recorded first results are not what a small team can casually maintain. Treating the gateway as the obvious home for cross-cutting concerns also overlooks that it is itself a single point of failure, a caveat the article notes before folding it back into "do it once at the boundary."

References & Further Reading

  • GraphQL Foundation, 2026. GraphQL Specification Versions — The published specification for the query language and type system that the GraphQL section describes.
  • gRPC Authors, 2026. Documentation | gRPC — Primary documentation for the schema-driven, binary-encoded RPC framework discussed in the gRPC section.
  • Stripe, 2026. Idempotent requests — First-party documentation of idempotency-key semantics in a payment API.