REST, RPC, GraphQL and Custom APIs: How to Choose?

Objectives

By the end of the lesson, you can compare the REST-style HTTP API, RPC/gRPC, GraphQL and the custom API, and justify which one fits when.

Why is it needed?

Several styles can coexist in one system: a public HTTP API, internal gRPC, GraphQL-based client aggregation. The choice depends on the consumer, the operation and the need for change, not on a ranking of the styles.

The same problem, different interfaces

One operation (for example creating a resource) can be expressed as: REST-style POST /items, then GET /items/42; in RPC CreateItem and GetItem; in GraphQL a mutation; in a custom protocol an item.create type of message. In each the same business rule, authorisation and repetition protection are required (6.5). The difference is in the expressive means of the interface, in tooling and in the consumer relationship.

Aspect	REST-style HTTP	RPC / gRPC	GraphQL	Custom API
Central concept	Resource, representation	Operation, typed message	Schema, field selection	Own contract
Strength	HTTP ecosystem, intermediaries, caching	Internal calls, generation, streaming	Differing client needs	Special requirement
Client tools	HTTP client, description language	Generated stub	Query, schema knowledge	Own client
Complex reads	Several endpoints or aggregation	Summary operation	Field-based query	Own operation
Main risk	Chatty API	Too fine-grained remote methods	Query cost, N+1	Incomplete own rules
Caching	Direct with HTTP tools	At application level	Depends on query and data model	By own rules

The table is not a quality ranking. A strength is an advantage only if the situation of use demands it.

Custom API

A custom API is one that defines its own operations and message rules, over HTTP or another transport. It need not be called REST to be good: it can use standard HTTP methods and statuses while the meaning of the content is its own contract. It can be justified for a special business operation, a legacy system or a simple integration. The limit is that common tools know less about the application meaning, so the contract must be described in a machine-processable way.

Consumer and trust boundary

For a public API, broad tool support, documentation and slow client updates matter. For internal services, a typed contract and common tools are easier to take on. For a browser, the available transports and authentication constrain the choice.

• GraphQL: if several clients use different subsets of the same graph.
• RPC: if the boundary publishes business operations.
• REST-style HTTP: if there is a stable resource life cycle and HTTP features (caching, conditional requests) help.
• Custom API: if none of them fits, at the price of maintaining more rules and tools in return for the freedom.

Coexistence and adapters

The external interface need not be identical to the internal one. A BFF (backend for frontend, discussed in detail in lesson 7.6) can accept a GraphQL query while requesting data from the services over gRPC and HTTP. The adapter must translate errors, time limits and the authorisation context; it must not hide every internal error as a successful empty response. Too many styles raise learning and operating costs, so the reason for variety must be documented, and common guidelines help.

Common misconceptions

Statement	Clarification
"GraphQL is the successor of REST."	Different trade-offs, they can coexist.
"gRPC is always faster."	It can be advantageous for internal calls; it is not direct from a browser.
"The name of the style ensures the correct state change."	The business rule, authorisation and repetition protection are style-independent.
"Every service may use something different."	Variety is a cost; common guidelines are needed.

In short

• The choice depends on the consumer, the operations and the need for change.
• REST gives HTTP tools, RPC a typed internal call, GraphQL field selection, a custom API a special contract.
• Several styles can live in one system, with adapters.
• The business rule is style-independent.

Review questions

1. Which style would you choose for an API serving many kinds of clients, and which for internal stock reservation?
2. What is the risk of too many API styles?
3. When is a custom API justified?

Learning resources

• Roy Fielding: REST architectural style
• gRPC core concepts
• GraphQL: Performance