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.organdpartners.example.orgcan reach the same gateway and go to different backends. - Path prefix. Everything under
/timetablegoes to the Timetable service. - Method. A
GETand aPOSTon 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.
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:
POSTon/courses/{code}/enrolmentsgoes to Student Records.GETon any path under/coursesgoes to the Courses service.- Any path under
/timetablegoes to the Timetable service. - 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.
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.