Introduction

The REST APIs provided by Diffusion allow users to manage and control Gateway clients. Multiple endpoints are available to retrieve information about registered and connected Gateway clients, including their configuration and status. Additionally, REST endpoints exist for managing services, adding and removing shared configurations, and starting, pausing and stopping gateway clients. Essentially, all the actions that can be performed on Gateway clients through the Diffusion management console can also be accomplished through the REST endpoints.

Enabling REST services

<rest-service>
    <rest-apis>
        <rest-api type="GATEWAY_CONTROL"></rest-api>
    </rest-apis>
</rest-service>
                

Inclusion of the rest-service tag configures the server to expose one or more REST APIs. With the inclusion of this tag at least one REST API must be configured using rest-apis tag. At the moment only REST API of type "GATEWAY_CONTROL" is supported. For more information on REST configuration XML tags see WebServer.xml.

Using the Gateway Control REST API

To access any REST endpoints, users must first make a call to the login endpoint including a Basic Authentication header. The response will include a session token, which must be included in the headers of all subsequent calls as an Authorization bearer token. The session token is generated by the server when the client successfully authenticates. When a call with a session token is made to an endpoint, the REST service verifies the token. By default, session tokens expire after 5 minutes. However, this duration can be set in the REST services configuration.

Examples and resources

The "Examples" folder in the Diffusion installation contains resources showing how to use the Gateway Control REST API. These are explained below.

Postman collection

examples/rest/gateway-control/GatewayControlRESTApis.postman_collection.json

A Postman collection including examples showcasing the usage of all the available endpoints for the Gateway Control REST API. By referring to this collection users can access a comprehensive set of sample requests that demonstrate how to interact with the Gateway control API. These examples serve as a practical reference for using the different endpoints and leveraging their functionalities effectively.

Open API Specification

examples/rest/gateway-control/gatewayControlRestApiOpenSpec.yaml

The OpenAPI specification for the Gateway Control REST API. It provides a comprehensive list of available endpoints that can be used to manage Gateway clients, along with detailed information on their usage. By referring to this file, users can easily access and understand the various endpoints and their corresponding functionalities for controlling Gateway clients.

Scope of session token

Diffusion session tokens are valid only to the server which issued them. Therefore, it is important that users use a sticky load balancer to ensure that REST calls are consistently delivered to the same server. Failure to do so will result in the login request being handled by one server, while subsequent calls are directed to a different server leading to authentication errors.

REST session management

When the login endpoint is called, a corresponding Diffusion session is created and linked to the generated session token. This Diffusion session can be observed in the Diffusion management console under the "sessions" tab.

If the Diffusion session is closed, then any associated REST session token is invalidated. This ensures that the session token remains synchronized with the status of the Diffusion session, providing a secure and reliable authentication mechanism.