Configuring Routes

Routes are JSON configuration files that handle requests and their context, and then hand off any request they accept to a handler. Another way to think of a route is like an independent dispatch handler, as described in "DispatchHandler".

Routes can have a base URI to change the scheme, host, and port of the request.

For information about the parameters of routes, see "Route".

Configuring Objects Inline or In the Heap

If you use an object only once in the configuration, you can declare it inline in the route and do not need to name it. However, when you need use an object multiple times, declare it in the heap, and then reference it by name in the route.

The following route shows an inline declaration for a handler. The handler is a router to route requests to separate route configurations: 

{
  "handler": {
    "type": "Router"
  }
}

The following example shows a named router in the heap, and a handler references the router by its name: 

{
  "handler": "My Router",
  "heap": [
    {
      "name": "My Router",
      "type": "Router"
    }
  ]
}

Notice that the heap takes an array. Because the heap holds all configuration objects at the same level, you can impose any hierarchy or order when referencing objects. Note that when you declare all objects in the heap and reference them by name, neither hierarchy nor ordering are obvious from the structure of the configuration file alone.

Setting Route Conditions

When a route has a condition, it can handle only requests that meet the condition. When a route has no condition, it can handle any request.

A condition can be based on a characteristic of the request, context, or IG runtime environment, such as system properties or environment variables. Conditions are defined using IG expressions, as described in "Expressions".

Because routes define the conditions on which they accept a request, the router does not have to know about specific routes in advance. In other words, you can configure the router first and then add routes while IG is running.

The following example shows a route with no condition. This route accepts any request: 

{
  "name": "myroute",
  "handler": {
    "type": "ReverseProxyHandler"
  }
}

The following example shows the same route with a condition. This route accepts only requests whose path starts with mycondition: 

{
  "name": "myroute",
  "handler": {
    "type": "ReverseProxyHandler"
  },
  "condition": "${matches(request.uri.path, '^/mycondition')}"
}

The following table lists some of the conditions used in routes in this guide:

Example Conditions and Requests
ConditionRequests That Meet the Condition

"${matches(request.uri.path, '^/login')}"

http://app.example.com/login, . . . 

"${request.uri.host == 'api.example.com'}"

http://api.example.com/, https://api.example.com/home, http://api.example.com:8080/home, . . . 

"${matches(contexts.client.remoteAddress, '127.0.0.1')}"

http://localhost:8080/keygen, http://127.0.0.1:8080/keygen, . . .

Where /keygen is not mandatory and could be anything else. 

"${matches(request.uri.query, 'demo=simple')}"

http://openig.example.com:8080/login?demo=simple, . . .

For information about URI query, see query in "URI". 

"${request.uri.scheme == 'http'}"

http://openig.example.com:8080, . . . 

"${matches(request.uri.path, '^/dispatch') or matches(request.uri.path, '^/mylogin')}"

http://openig.example.com:8080/dispatch, http://openig.example.com:8080/mylogin, . . . 

"${request.uri.host == 'sp1.example.com' and not matches(request.uri.path, '^/saml')}"

http://sp1.example.com:8080/, http://sp1.example.com/mypath, . . .

Not http://sp1.example.com:8080/saml, http://sp1.example.com/saml, . . . 

"condition": "${matches (request.uri.path, '&{uriPath}')}"

http://openig.example.com:8080/hello, when the following property is configured: 

{
  "properties": {
    "uriPath": "hello"
  }
}

For information about including properties in the configuration, see Properties. 

"condition": "${request.headers['X-Forwarded-Host'][0] == 'service.example.com'}"

Requests with the header X-Forwarded-Host, whose first value is service.example.com.


Configuring Route Names, IDs, and Filenames

The filenames of routes have the extension .json, in lowercase.

The Router scans the routes folder for files with the .json extension, and uses the route's name property to order the routes in the configuration. If the route does not have a name property, the Router uses the route ID.

The route ID is managed as follows:

  • When you add a route manually to the routes folder, the route ID is the value of the _id field. If there is no _id field, the route ID is the filename of the added route.

  • When you add a route through the Common REST endpoint, the route ID is the value of the mandatory _id field.

  • When you add a route through Studio, you can edit the default route ID.

Caution

The filename of a route cannot be default.json, and the route's name property and route ID cannot be default.

Read a different version of :