Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Gateway Routing

One address for clients and a table of rules behind it: what a rule can match, which rule wins when two match, rewriting the path on the way, and moving a backend without changing any client.

The catalogue is moving out

A university's student app sends everything to one address, api.example.org: the course catalogue, enrolments, the weekly timetable. For years one system answered all of it, Student Records. Now a team has built a new Courses service and wants the catalogue served from there, without shipping a new app to the forty thousand phones that have it installed, some of which will not update for months.

Gateway Routing is what makes that possible. Clients know a single endpoint; behind it, a gateway holds a table of rules, and each rule says which requests go to which backend. Moving the catalogue is a change to the table, not to every client. Had the app been built with Student Records' own address inside it, the move would wait for every installed copy to update, or for something at that old address to forward the requests on, and so would every later relocation. The table changes where a request goes, not what it says, so clients stay untouched only while the new backend answers the same requests the same way.

What a rule can look at

A rule matches on parts of the request the gateway can read without understanding the request's meaning:

  • Host. api.example.org and partners.example.org can reach the same gateway and go to different backends.
  • Path prefix. Everything under /timetable goes to the Timetable service.
  • Method. A GET and a POST on the same path can go to different backends.
  • Header. A header the client sends, such as X-Api-Version, can choose between two builds of the same API.
Route by method and path

The app knows one address. Catalogue reads go to the new Courses service; enrolling, and everything not moved yet, still go to Student Records.

Moving the reads first

The team moves the catalogue's reads first. Enrolling writes to Student Records, which checks prerequisites and free seats, so it moves later. The table, in the order it is written:

  1. POST on /courses/{code}/enrolments goes to Student Records.
  2. GET on any path under /courses goes to the Courses service.
  3. Any path under /timetable goes to the Timetable service.
  4. Everything else goes to Student Records.

Rule 4 is the catch-all that keeps the old system answering whatever has not moved yet. Taking a monolith apart this way, one route at a time while the rest keeps working, has a name of its own: Strangler Fig.

Changing the path on the way

The Courses service was written to serve its entries at /catalogue/{code}, not /courses/{code}. Rather than rename its endpoints, the rule can rewrite the path: the gateway receives /courses/cs101 and forwards /catalogue/cs101. Anything the service sends back that contains its own paths now leaks the internal one, such as the Location header of a redirect: the app is told to fetch /catalogue/cs101, which only the catch-all matches, so it falls through to Student Records, which has never heard of it. Either the service is told its public path, or the gateway rewrites that header on the way back as well.

The same table can serve versions: /v2/courses to a new build and /courses to the old one, or the X-Api-Version header choosing between them. The rule only decides where each version is served; how long to keep the old one, and what counts as a breaking change, are questions for API versioning & backwards compatibility. A rule can also split one path by weight, say 5% of /courses to a new build while the rest stays on the old one, which is the mechanism under a canary in Progressive delivery: blue-green, canary & rollback.

NoteRouting is one of three jobs that the same gateway component often does, with aggregation and offloading; API gateway & the edge sets out all three and what the component costs.

When two rules match

A POST /courses/cs101/enrolments matches rule 1, and rule 4 too. Which one wins depends on the gateway. Some evaluate rules in the order they are written and take the first match; Envoy does this with the routes of a virtual host. Others prefer the most specific match; among its prefix locations, NGINX picks the longest matching prefix. With first-match, order is part of the configuration and specific rules go above general ones. With most-specific, order matters less, but you need to know how your gateway ranks a template like {code} against a plain prefix.

Two weeks before enrolment opens, someone tidies the table and puts a single rule at the top: any path under /courses goes to the Courses service, whatever the method. In a first-match gateway, enrolment requests now reach a service that has no such endpoint and answers 404 or 405. Everything else works: the catalogue loads, the timetable loads, the gateway is healthy. A routing mistake usually looks like this, one kind of request failing with an error from a service that should never have seen it. Two habits catch it: logging, for each request, which rule matched and which backend answered, and keeping a short list of sample requests with the backend each must reach, checked against every change to the table before it ships.

In the API Gateway Patterns Challenge, the rules written on the Gateway Routing node's edges are where this mistake is made or prevented. Read yours the way a first-match gateway would, top to bottom, holding POST /courses/cs101/enrolments, and see which Service it reaches. Then picture one more path leaving Student Records: if the Client's edge to the gateway has to change, a client still knows more than the single address.

Practice this