Creating and Editing Routes Through Common REST

Note

When IG is in production mode, you cannot manage, list, or even read routes through Common REST. For information about switching to development mode, see "Switching from Production Mode to Development Mode".

Note

If an AM policy agent is configured in the same container as IG, by default the policy agent intercepts requests to manage routes. When you try to add a route through Common REST, the policy agent redirects the request to AM and the route is not added.

To override this behavior, add the URL pattern /openig/api/* to the list of not-enforced URI in the policy agent profile. For more information about configuring policy agents, see the Java Agent's User Guide.

Through Common REST, you can read, add, delete, and edit routes on IG without manually accessing the file system. You can also list the routes in the order that they are 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, see "About ForgeRock Common REST".

To Manage Routes Through Common REST

Before you start, prepare IG as described in Getting Started Guide.

  1. Add the following route to IG: 

    $HOME/.openig/config/routes/00-crest.json
    %appdata%\OpenIG\config\routes\00-crest.json
    {
  "name": "crest",
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "reason": "OK",
      "headers": {
        "Content-Type": [ "text/plain" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${matches(request.uri.path, '^/crest')}"
}

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

  2. To read a route through Common REST:

    • Enter the following command in a terminal window: 

      $ curl -v http://openig.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.

  3. To add a route through Common REST:

    • Move $HOME/.openig/config/routes/00-crest.json to /tmp/00-crest.json.

    • 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://openig.example.com:8080/crest. You should get an HTTP 404 error.

    • Enter the following command in a terminal window: 

      $ curl -X PUT http://openig.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.

    • 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://openig.example.com:8080/crest. You should see the "Hello world!" message.

  4. To edit a route through Common REST:

    • Edit /tmp/00-crest.json to change the message displayed by the response handler in the route.

    • Enter the following command in a terminal window: 

      $ curl -X PUT http://openig.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.

    • 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://openig.example.com:8080/crest to confirm that the displayed message has changed.

  5. To delete a route through Common REST:

    • Enter the following command in a terminal window: 

      $ curl -X DELETE http://openig.example.com:8080/openig/api/system/objects/_router/routes/00-crest

    • 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://openig.example.com:8080/crest. You should get an HTTP 404 error.

  6. To list the routes deployed on the router, in the order that they are tried by the router:

    • Enter the following command in a terminal window: 

      $ curl "http://openig.example.com:8080/openig/api/system/objects/_router/routes?_queryFilter=true"

      The list of loaded routes is displayed.

Read a different version of :