REST vs RPC
REST models resources with uniform HTTP semantics, while RPC models actions as named procedures. The choice shapes caching, coupling, tooling, and client evolution.
Definition
REST and RPC are contrasting API styles: REST exposes resources manipulated through uniform HTTP methods and representations, while RPC exposes named procedures invoked with typed parameters, often over a custom or binary protocol.
Context and scope
Choose between them when designing a new API boundary; the decision affects caching, public consumption, and how tightly clients bind to server behavior.
Common misconceptions
- REST means JSON over HTTP; JSON alone does not make an API RESTful, uniform methods and cacheability do
- RPC is obsolete; gRPC powers a large share of internal infrastructure
- One style must be used everywhere; public and internal APIs can differ
Anti-patterns
- Wrapping every operation in POST /doSomething and calling it REST
- Forcing resource modeling onto inherently procedural workflows
- Changing transport semantics while claiming backward compatibility
Related concepts
Related examples
Authoritative source
https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design
How it works
REST treats the API as a set of resources identified by URLs, manipulated with the uniform methods GET, POST, PUT, PATCH, and DELETE. Semantics come from HTTP: safe methods, idempotency, status codes, caching, and content negotiation. RPC treats the API as a set of procedures — CreateOrder, CancelOrder, GetQuote — with typed inputs and outputs, and the transport is mostly an implementation detail.
POST /orders/123/cancel HTTP/1.1rpc CancelOrder(CancelOrderRequest) returns (Order);Both can be valid. The difference is what the contract centers on: a resource’s state transitions, or a named operation.
When to use it
REST fits public APIs, CRUD-heavy domains, and anything that benefits from HTTP caches, links, and generic tooling. RPC fits internal calls with rich typed contracts, streaming, and performance-sensitive paths. Many systems combine them: REST at the edge for clients and caching, gRPC inside for service-to-service traffic.
Trade-offs
REST’s uniform interface buys cacheability and familiarity but strains on procedural workflows, where teams invent action endpoints anyway. RPC buys precision and code generation but weakens HTTP caching, and clients bind more tightly to method signatures. Public RPC APIs need careful versioning and error mapping. Neither style fixes poor resource design or missing idempotency.
Example and misconceptions
A payment API illustrates the split. GET /payments/123 and POST /payments are natural REST resources. POST /payments/123/capture is a legitimate action that REST modeling handles awkwardly; a CapturePayment RPC expresses it directly. Calling the first design “REST” and the second “not REST” misses the point — both are HTTP APIs with different centers of gravity.
Related concepts: gRPC, API Versioning, and Idempotency.