REST Between Services

Analogy categoryAnalogies

REST as the Default Language of Microservices

Representational State Transfer (REST) has become the default protocol for synchronous communication between microservices because it maps naturally onto HTTP, the ubiquitous transport that every language, proxy, load balancer, and monitoring tool already understands. A RESTful API models each service's data as resources addressed by URLs, such as /orders/42 or /customers/17/invoices, and uses HTTP verbs (GET, POST, PUT, PATCH, DELETE) to express operations on those resources rather than inventing custom action names. This uniformity means a new engineer can guess the shape of an unfamiliar service's API just from knowing REST conventions.

🏏

Cricket analogy: Just as every cricket scorecard follows the same universal structure of overs, runs, and wickets regardless of which league you're watching, a RESTful API follows the same GET/POST/PUT conventions regardless of which team built the service.

Designing Resource-Oriented Endpoints

Good REST design in a microservices context means modeling nouns, not verbs: an orders service exposes /orders and /orders/{id}, not /getOrder or /createNewOrder. Nested resources express relationships, such as GET /customers/17/orders to list a customer's orders, while query parameters handle filtering, pagination, and sorting, like GET /orders?status=shipped&page=2. Status codes carry meaning beyond success or failure — 201 Created for a successful POST, 404 Not Found for a missing resource, 409 Conflict for a version mismatch — so clients can react programmatically without parsing error strings.

🏏

Cricket analogy: Modeling /orders/{id}/items as a nested resource is like a scorecard nesting each batsman's individual ball-by-ball entries under the innings total, keeping the hierarchy of who-belongs-to-what clear.

Versioning and Backward Compatibility

Because REST APIs between microservices are contracts that other teams depend on, breaking changes must be handled deliberately. Common strategies include URL versioning (/v1/orders vs /v2/orders), header-based versioning (Accept: application/vnd.orders.v2+json), or simply designing changes to be additive — adding new optional fields rather than renaming or removing existing ones. Consumer-driven contract testing, where the consuming service's expectations are codified as tests run against the provider, catches accidental breaking changes before they reach production and break a downstream team's service.

🏏

Cricket analogy: URL versioning like /v1/orders and /v2/orders is like the ICC maintaining separate rule sets for Test cricket and T20 cricket side by side, so existing formats keep working while a new format is introduced.

http

POST /v1/orders HTTP/1.1
Host: orders.internal.svc
Content-Type: application/json

{
  "customerId": 17,
  "items": [{ "sku": "ABC-123", "quantity": 2 }]
}

HTTP/1.1 201 Created
Location: /v1/orders/42
Content-Type: application/json

{
  "orderId": 42,
  "status": "pending",
  "total": 59.98
}

GET /v1/customers/17/orders?status=shipped&page=2 HTTP/1.1
Host: orders.internal.svc

Using REST for chatty, fine-grained interactions between tightly coupled services (dozens of small calls per request) causes network overhead and latency to dominate. If two services need to exchange many small pieces of data per interaction, consider gRPC or batching the REST calls into a single coarser-grained endpoint.

Idempotency matters over unreliable networks: PUT and DELETE should be safe to retry without side effects, and POST endpoints that create resources should accept an idempotency key so a retried request doesn't create a duplicate order.

REST models microservice APIs as resources (nouns) addressed by URLs, manipulated via standard HTTP verbs.
Nested resources like /customers/{id}/orders express relationships between entities cleanly.
HTTP status codes (201, 404, 409, etc.) carry semantic meaning that clients can act on programmatically.
Versioning strategies (URL or header-based) and additive changes protect downstream consumers from breaking changes.
Consumer-driven contract testing catches breaking changes before they reach production.
Idempotency keys protect POST endpoints from creating duplicates when clients retry after network failures.
REST is best for coarse-grained, human-readable service interactions, not high-frequency chatty internal calls.