API Architecture: REST, GraphQL, gRPC, Gateways & BFF

Q: REST, GraphQL, or gRPC — how do I choose?

Use REST for CRUD-style public APIs and broad compatibility; it's simple and cacheable. Use GraphQL when clients need flexible, nested queries and you want to avoid over/under-fetching (great for mobile and rich frontends), accepting harder caching and added complexity. Use gRPC for high-performance internal service-to-service calls where binary efficiency and strong contracts matter and browser support isn't required. Many systems use more than one.

API Architecture Patterns

Well-designed APIs are the contract that lets systems and teams evolve independently. Architecture here is about the decisions that are expensive to change later: which API style fits the use case, how you version, how you paginate, how errors are shaped, and how cross-cutting concerns (auth, rate limiting, routing) are handled at the edge.

The recurring theme is design for change. APIs are long-lived public contracts — versioning from day one and favoring backward compatibility costs little up front and saves painful migrations when consumers depend on you.

TL;DR

Choose the API style by use case (REST, GraphQL, gRPC, WebSockets).
Version APIs from day one.
Design for backward compatibility.
Use API gateways for cross-cutting concerns.

Quick Example

Resource-oriented URLs — nouns and HTTP verbs, not RPC-style actions:

Choosing an API Style

💡 Resource-oriented design (/api/users/123) beats RPC-style URLs (/api/getUser) for REST — let the HTTP verb express the action. See REST API Design.

Versioning

See API Versioning.

Pagination

Cursor-based scales; offset-based is simpler but degrades on large datasets:

Error Responses

Consistent, machine-readable error shapes let clients handle failures programmatically:

See Error Handling.

Gateway & BFF Patterns

API Gateway

A single entry point that handles cross-cutting concerns so services don't each reimplement them:

Backend for Frontend (BFF)

A tailored API per client type, each shaped to that client's needs:

Web BFF returns larger payloads; mobile BFF trims for bandwidth; a partner API offers a stable, versioned contract.

GraphQL Schema Design

See GraphQL.

Best Practices

Pick the style to fit the use case — don't default to one for everything.
Version from day one and evolve backward-compatibly (add, don't rename/remove).
Use cursor pagination for large or fast-changing collections.
Standardize error shapes across the whole API.
Centralize cross-cutting concerns in a gateway; tailor per-client with BFFs.

Common Mistakes

RPC-style URLs in a REST API

Offset pagination on large datasets

FAQ

REST, GraphQL, or gRPC — how do I choose?

Use REST for CRUD-style public APIs and broad compatibility; it's simple and cacheable. Use GraphQL when clients need flexible, nested queries and you want to avoid over/under-fetching (great for mobile and rich frontends), accepting harder caching and added complexity. Use gRPC for high-performance internal service-to-service calls where binary efficiency and strong contracts matter and browser support isn't required. Many systems use more than one.

Why version APIs from day one?

Because the moment a consumer depends on your API, changing it breaks them. Versioning gives you a path to evolve — ship v2 while v1 keeps working — without forcing every client to update in lockstep. Adding it after launch means retrofitting a contract people already rely on. Even if you only ever have v1, the structure costs almost nothing and preserves your options.

When should I use an API gateway?

When you have multiple services and want to handle cross-cutting concerns — authentication, rate limiting, routing, response aggregation, protocol translation — in one place rather than duplicating them in each service. A gateway gives clients a single entry point and a stable surface while services evolve behind it. For a single small service, a gateway may be unnecessary overhead.

What is a Backend for Frontend (BFF) and when do I need one?

A BFF is a dedicated API layer tailored to a specific client (web, mobile, partner), aggregating and shaping data for that client's needs rather than forcing one generic API to serve all. You need it when different clients have meaningfully different requirements — a mobile app wanting small bandwidth-optimized payloads vs a web app wanting richer data. It avoids bloating a shared API with client-specific concerns.