CSE Roadmap

Common tier · about 3 hours · 9 parts

Part 5 of 9 · 2 min read

Routing and translation

A routing map that keeps old public paths alive, and a gateway that speaks different protocols to different clients.

Think of a switchboard in an old office. A caller dials a public extension, and the operator connects the line to whichever desk now handles that job. If the department moves to another floor, the public extension stays the same.

The gateway's routing map does this. The book gives an example. The map may link an external path to an internal one one-to-one. If the internal path changes in the future, the public API can keep the old path, so old clients still work.

A small routing map:

Public call Internal target
GET /v1/products/{id} product-service: GET /items/{id}
GET /v1/cart cart-service: GET /carts/by-user/{user}
POST /v1/orders order-service: POST /orders

If the product team renames /items to /catalog, only the map changes. The public path GET /v1/products/{id} is unchanged, and no app needs an update. This connects to page 2: the gateway lets internal services change at their own speed while the public contract stays steady.

Translation is the second job. The book gives two cases.

  • Protocol change. The gateway turns a public REST call into an internal gRPC call (page 2). Outside users get a simple, widely supported API. Inside, services get a fast and strict one.
  • Different APIs for different clients. A web page on a desktop can show more data than a phone screen. Phones also save battery by sending fewer requests. The gateway can offer one shape of reply to the desktop and another to the phone.

An increasingly popular method, the book says, is a graph-based API such as GraphQL. The client states what data it needs, and the gateway turns that into a series of internal calls. This removes the need to write a different endpoint for every screen. The book adds a reminder: there is still an API. It is simply described by a graph schema, and it lets clients make limited queries over the internal services.

A worked example. A phone home screen needs 12 fields from 3 services. A desktop home page needs 40 fields from the same services.

  • Without a gateway, each client calls three services and discards what it does not need, and the phone downloads fields it never shows.
  • With a gateway, GET /home?client=phone returns the 12 fields. Suppose each field is about 100 bytes: 1,200 bytes against 4,000 for the desktop. The phone saves 2,800 bytes per call, and 1 request instead of 3.
  • At a 150 ms round trip from the phone, three requests in turn cost 450 ms, and one costs about 150 ms.

Common mistake

Letting the gateway take on business rules, such as price calculation. It becomes a second application that every team must edit. Keep the gateway thin: routing, shaping, protection. Business rules belong in the services.

Check yourself:

  • If an internal path changes, what changes at the gateway, and what stays the same for clients?
  • Why might a phone and a desktop get different shapes of reply?