Junction Status REST API

Edit online

The junction status REST API provides a mechanism by which an external client can determine the status of hosted junctions and junctioned servers. It can be used as an alternative to the junction show server task command.

Security Considerations

This API can potentially expose sensitive information to callers of the API. For example, it can be used to determine if all replicated junctioned servers are available or not. As a result of this, an administrator should take care to only enable this API on systems with controlled network access. The administrator should also ensure that the ACL which protects this API is appropriately restrictive on access.

The state information, for only those junctions which are accessible to the authenticated user, will be returned. This authorisation is controlled by the ‘r’ ACL permission bit on the junction object.

Configuration

To enable the junction status REST API, a configuration entry for the API that is used to map the API to a specific URI, must be added to the [local-apps] stanza. The supplied URI must define a single path segment. In other words, it must not include multiple '/' and will be relative to the root of the local junction.
[local-apps]
jct-status = jctstatus
In the configuration example above, the junction status REST API is enabled and mapped to the jctstatus path segment. If the local junction is configured with a path of '/', which is the standard local junction path in a WebSEAL environment, the junction status REST API can be accessed at the following URL:
http[s]://<webseal-host>:<webseal-port>/jctstatus
For example:
https://www.ibm.com/jctstats

API Definition

A single API is provided by the junction status decision application:
Method:
GET
Query Arguments:
junction (optional)
The name of the junction for which the state information will be returned. If no junction is specified, the state of all hosted junctions will be returned.
Request Examples:
GET /jctstatus
GET /jctstatus?junction=/app
Response Code
200
The request was successful.
Response Body
junctions
The top level object which contains an array of junction objects. This is only included in the response if the status of all junctions has been requested.
junctions[].name
The name of the junction.
junctions[].servers
An array of objects which show the status of servers used by the junction.
junctions[].servers[].identifier
The identifier of the server.
junctions[].servers[].healthy
A boolean which is used to indicate whether the server is currently healthy or not.
junctions[].servers[].state
A description of the state of the server. The options are: running, not running, invalid, unknown.
Response Example
{
  "junctions": [
	  {
	    "name": "/jct",
	    "servers": [
	      {
		  "identifier": "f9af717e-dd05-11eb-8af9-000c299bdb27",
		  "healthy": true,
		  "state": "running"
        }
	    ]
	  }
  ]
}
400 Bad Request / 404 Not Found / 500 Internal Server Error
An issue was found with the request which prevented the junction status from being returned. The contents of the response is governed by the configuration of the static error pages for the WebSEAL instance.