Routes and Common REST

When PingGateway is in production mode, you can’t manage, list, or read routes through Common REST. For information about switching to development mode, refer to Operating modes.

Through Common REST, you can read, add, delete, and edit routes on PingGateway without manually accessing the file system. You can also list the routes in the order that they’re loaded in the configuration, and set fields to filter the information about the routes.

The following examples show some ways to manage routes through Common REST. For more information, refer to About ForgeRock Common REST.

Manage routes through Common REST

Before you start, prepare PingGateway as described in the Quick install.

Add the following route to PingGateway:

Linux
Windows

$HOME/.openig/config/routes/00-crest.json

%appdata%\OpenIG\config\routes\00-crest.json

{
  "name": "crest",
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${find(request.uri.path, '^/crest')}"
}

To check that the route is working, access the route on: http://ig.example.com:8080/crest.

To read a route through Common REST:
1. Enter the following command in a terminal window:
  $ curl -v http://ig.example.com:8080/openig/api/system/objects/_router/routes/00-crest\?_prettyPrint\=true
  The route is displayed. Note that the route _id is displayed in the JSON of the route.
To add a route through Common REST:
1. Move $HOME/.openig/config/routes/00-crest.json to /tmp/00-crest .json.
2. Check in $HOME/.openig/logs/route-system.log that the route has been removed from the configuration, where $HOME/.openig is the instance directory. To double check, go to http://ig.example.com:8080/crest. You should get an HTTP 404 error.
3. Enter the following command in a terminal window:
  $ curl -X PUT http://ig.example.com:8080/openig/api/system/objects/_router/routes/00-crest \ -d "@/tmp/00-crest.json" \ --header "Content-Type: application/json"
  This command posts the file in /tmp/00-crest.json to the routes directory.
4. Check in $HOME/.openig/logs/route-system.log that the route has been added to configuration, where $HOME/.openig is the instance directory. To double-check, go to http://ig.example.com:8080/crest. You should see the "Hello world!" message.
To edit a route through Common REST:
1. Edit /tmp/00-crest.json to change the message displayed by the response handler in the route.
2. Enter the following command in a terminal window:
  $ curl -X PUT http://ig.example.com:8080/openig/api/system/objects/_router/routes/00-crest \ -d "@/tmp/00-crest.json" \ --header "Content-Type: application/json" \ --header "If-Match: *"
  This command deploys the route with the new configuration. Because the changes are persisted into the configuration, the existing $HOME/.openig/config/routes/00-crest.json is replaced with the edited version in /tmp/00-crest.json.
3. Check in $HOME/.openig/logs/route-system.log that the route has been updated, where $HOME/.openig is the instance directory. To double-check, go to http://ig.example.com:8080/crest to confirm that the displayed message has changed.
To delete a route through Common REST:
1. Enter the following command in a terminal window:
  $ curl -X DELETE http://ig.example.com:8080/openig/api/system/objects/_router/routes/00-crest
2. Check in $HOME/.openig/logs/route-system.log that the route has been removed from the configuration, where $HOME/.openig is the instance directory. To double-check, go to http://ig.example.com:8080/crest. You should get an HTTP 404 error.
To list the routes deployed on the router, in the order that they are tried by the router:
1. Enter the following command in a terminal window:
  $ curl "http://ig.example.com:8080/openig/api/system/objects/_router/routes?_queryFilter=true"
  The list of loaded routes is displayed.

PingGateway 2024.6

Routes and Common REST