Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Communication

Synchronous Communication with HTTP APIs

Connect microservices with HTTP APIs: design contracts, set timeouts, make POST requests safe to retry with idempotency keys, and call a service from another.

The simplest way for one service to ask another for something is a synchronous call: send a request, wait, get a response. In most systems that means an HTTP API, usually JSON over REST. It is familiar, easy to debug with a browser or curl, and works from every language.

The catch is that a synchronous call couples the caller to the callee in time. If the callee is slow, the caller is slow. If the callee is down, the caller has a problem right now. This lesson shows how to design the call well: a clear contract, a timeout on every request, and idempotency so that retries are safe. You met the reasons in The Fallacies of Distributed Computing; here we apply them.

A good service-to-service call

A contract Both sides know the shape of requests and replies.
A timeout Never wait forever.
Idempotency Repeating a request does no harm.
Clear errors Status codes the caller can act on.

Skip any of the four and failures get expensive.

1 / 2

Why REST works between services

REST is a style, not a protocol: resources have URLs (/products/42), and the HTTP method says what to do with them. For service-to-service calls the useful parts are:

  • Methods with meaning. GET reads and is safe to repeat. PUT and DELETE are idempotent by definition. POST creates something and is not idempotent unless you make it so.
  • Status codes. 200 and 201 mean success, 400 means the request was wrong (do not retry), 404 means not found, 429 means slow down and 503 means the service is temporarily unavailable (a retry may help).
  • Plain text on the wire. JSON is easy to read, log and replay.

Prefer coarse, business-meaningful endpoints (POST /orders) over thin database wrappers (POST /order-rows). A caller should not need to make five requests to do one thing.

The contract

A contract is the agreement between caller and callee: which URLs exist, what the request body must contain, what the response looks like and which errors can happen. Without one, every change in the callee is a roll of the dice for its callers.

Many teams write the contract in an OpenAPI document. The snippet below is real configuration, shown read-only because the site cannot run an API server for you. It describes one endpoint.

YAML
openapi: 3.1.0
info:
  title: Inventory API
  version: 1.0.0
paths:
  /stock/{sku}:
    get:
      summary: Read the stock level of one product
      parameters:
        - name: sku
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Stock level found
          content:
            application/json:
              schema:
                type: object
                required: [sku, available]
                properties:
                  sku: { type: string }
                  available: { type: integer, minimum: 0 }
        "404":
          description: Unknown product

The contract is the thing you version and test. Evolving it without breaking callers is the subject of API Versioning and Evolving Contracts, and checking it automatically is covered in Testing Microservices.

Two services, one real call

The stand-in below is real HTTP, not a simulation of it. It starts two small servers on the loopback interface inside one Node program: an inventory service and an orders service. The orders service calls inventory with fetch before accepting an order. Only the deployment is faked: in production these would be separate processes on separate machines.

Node.js Orders calls inventory over HTTP

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice how the orders service translates the inventory's answers into its own: inventory's 404 becomes orders' 400 (the caller's request was bad), and available: 0 becomes 409. Each service owns its own public language; it does not just forward whatever came back.

Timeouts: the most important setting

fetch has no timeout by default. If the callee accepts the connection and never answers, your request waits until some distant system limit. While it waits, it holds a connection, memory and usually a worker. A hundred such calls can exhaust a service that is otherwise healthy.

Always set a timeout on every outbound call, and choose it from the callee's real latency (for example, a little above its 99th percentile), not a round number. Node's AbortSignal.timeout(ms) aborts a request after the given time.

Node.js A slow service and a timeout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A timeout turns "wait unknown time" into a definite failure that your code can handle: return a fallback, report an error, or retry. How to retry without making things worse is the topic of Timeouts, Retries and Exponential Backoff.

When a request times out, you do not know whether the callee did the work. It may have finished just after you gave up. That uncertainty is why idempotency matters.

Idempotency: making POST safe to repeat

An operation is idempotent if doing it twice has the same effect as doing it once. GET, PUT and DELETE already are. POST /payments is not: a retry after a timeout could charge the customer twice.

The standard fix is an idempotency key. The caller generates a unique key for each logical operation and sends it in a header (Idempotency-Key: 7f3a...). The callee stores the result under that key. If the same key arrives again, it returns the stored result instead of repeating the work.

Node.js Idempotency key on a payment endpoint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The retry returns the same charge and does not create a second one. A production implementation also handles two identical requests arriving at the same moment (for example with a unique database constraint) and expires old keys after a while. It also compares the request body, so a reused key with different content is rejected. The Transactional Outbox and Idempotent Consumers shows the same idea on the receiving side of messages.

The limits of synchronous calls

Chains of synchronous calls multiply risk. If service A calls B, which calls C, then A is only available when all three are, and its latency is the sum of all three. If each is up 99.9 percent of the time, a chain of three is up about 99.7 percent. Deep chains also tend to be a sign that service boundaries are wrong.

Use synchronous calls when the caller truly needs the answer to continue (checking a price, validating a token). When the caller only needs to announce that something happened, prefer messages, which you will meet next in Asynchronous Messaging and Events.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should every outbound HTTP call between services have a timeout?

    A call with no timeout can wait very long and exhaust connections and workers, turning one slow service into a wider outage.
  2. 2. Which HTTP method is NOT idempotent by default?

    POST usually creates something new each time. It needs an idempotency key to be safe to retry.
  3. 3. A payment request times out. What do you know about whether the payment happened?

    A timeout means the caller stopped waiting, not that the callee stopped working. Retrying needs idempotency to avoid a double charge.
  4. 4. What does an idempotency key let the callee do?

    The callee stores the outcome under the key; the same key returns the same outcome.
  5. 5. In the orders and inventory stand-in, why did orders turn inventory's 404 into its own 400?

    From the shop customer's view, the request named an unknown product, which is a bad request to the orders API.

Summary

  • Synchronous HTTP calls are simple and universal, but they couple caller and callee in time.
  • Write the contract down (for example OpenAPI) and treat it as something you version and test.
  • Set a timeout on every outbound call, based on the callee's real latency.
  • Make non-idempotent operations such as POST /payments safe to retry with an idempotency key.
  • Translate errors into your own contract instead of forwarding them, and avoid deep synchronous chains.

Next: Asynchronous Messaging and Events.