Skip to main content

Route requests to a backend

A route is the first thing a request meets. It says which requests the gateway takes and where it sends them. This guide creates orders-api, a route that takes GET and POST requests for /orders and everything under it and sends them to two backend nodes of the orders backend. At the end, your clients call one address on the gateway, and the two backend nodes share the traffic behind it.

Before you start​

  • The address and port of each backend node, reachable from the gateway nodes. This guide uses 10.0.1.10:8080 and 10.0.1.11:8080.
  • The requests below call /orders/42, and once /orders itself.
  • For the last step, an environment whose Gateway URL is set. A Platform administrator sets it in Add an environment. Without it the route works, but the console cannot show you its address.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • This guide creates orders-api with no plugin. The guides that follow start from the route as this guide, or Share a backend between routes, leaves it.
  • The Editor or Environment administrator role in this environment. A Viewer sees routes but has no New route button.

Steps​

1. Open a new route and name it​

In the menu, select Routes, then New route. Under General, set Name to orders-api. The name is for people; the gateway does not match on it.

2. Say which requests the route takes​

Under Matching, in Paths, type a value and press Enter for each: /orders, then /orders/*. Both are needed: /orders/* takes everything under /orders/ but not /orders itself.

Under Methods, check GET and POST. Leave Hosts, Client addresses and Priority empty. With no hosts listed, the route takes requests for any host name. This Priority belongs to the route and orders the routes that share a path and a host.

3. Send the requests to your two backend nodes​

Under Target, choose Nodes on this route. Use this choice when only this route sends to these backend nodes. When several routes will share them, create them once as an upstream instead, as Share a backend between routes shows.

Nodes is already chosen inside. Select Add entry and fill in the first row, then select it again for the second row.

HostPortWeight
10.0.1.1080801
10.0.1.1180801

Each row also has a Priority of its own. It belongs to the backend node, not to the route like the one in step 2. Leave it empty in both rows, and leave the other settings of the section as they are. Two backend nodes with the same weight share the traffic.

The Target section of the new-route form, with Nodes on this route chosen and the two backend nodes filled in.

4. Create the route​

Select Create route. The console opens the route you created. It is saved like this:

route · as the console saves it
{
  "name": "orders-api",
  "uris": [
    "/orders",
    "/orders/*"
  ],
  "methods": [
    "GET",
    "POST"
  ],
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "10.0.1.10:8080": 1,
      "10.0.1.11:8080": 1
    }
  }
}

5. Find the address clients call​

On the route's Overview tab, the Address line shows one address for each path. Each address is the environment's Gateway URL, then the path. The address for /orders/* ends in /orders/ and carries a small prefix label. Copy address beside a line copies it.

The Overview tab of orders-api, with the Address line showing both paths.

No Address line means the environment has no Gateway URL yet. A Platform administrator sets it under Environments.

Check it​

Send a request to /orders/42, then one to /orders itself, one as a POST and one as a DELETE.

curl
curl -i -L 'https://<gateway host>/orders/42'

The request to /orders/42 is answered 200 by your backend.

Sent to /orders itself
A request to /orders itself is answered 200 as well.
Sent as a POST
A POST is answered 200 like a GET.
Sent as a DELETE
A DELETE, a method the route does not list, is answered 404 Route Not Found: no route takes it.

What to know​

  • A trailing * does not take the path itself. /orders/* takes /orders/ and what is under it, not /orders. List /orders as a second path when it has to answer too.
  • While one of the two backend nodes is stopped, clients keep getting answers. A request the stopped backend node refuses is tried on the other, a GET and a POST alike. An active health check on an upstream takes a stopped backend node out of rotation, so requests stop trying it first. Share a backend between routes sets one up.
  • A backend that has not answered within the route's Timeouts is given up on, and the client receives 504 Gateway Time-out. Connect, send and read are set together; without them the gateway waits its own, longer time for the backend.
  • Plugins are added once the route exists, on its Plugins tab. Require an API key adds the first one.
G8 dev