Connect to Knox via Admin API

Overview

Knox provides an Admin REST API to manage the administrator functions of the gateway: topology management, working with descriptors, provider configs, and aliases. This article shows several examples of using the API. To get a full list of available endpoints and methods, refer to the Knox Admin API documentation.

A simple way to create a query is to use curl and it’s going to be demonstrated below, but you can construct requests in any convenient way.

A template request looks like this:

$ curl -iu <login>:<password> -H <header> -d '<data>' -X <request_type> https://<gateway-host>/gateway/admin/api/v1/<endpoint>

where:

  • <login> — admin username.

  • <password> — password for <login>.

  • <header> — header to send with a request. It should mark the type of content you send or expect to receive (JSON or XML).

  • <data> — data to be sent with the request (JSON or XML). Omit if the request type is DELETE or GET.

  • <request_type> — type of the HTTP request (GET, POST, PUT, DELETE). If the request type is DELETE, remove the -H parameter from the command.

  • <gateway-host> — a Knox Gateway host with a port (e.g. https://stikhomirov-adps.ru-central1.internal:8443).

  • <endpoint> — resource to which the request will be sent.

NOTE
If the authentication is not enabled, omit the <login> and <password> parameters, and use the -k flag instead of -u.

The -i option allows you to see the HTTP headers and check the status of the request, feel free to remove it if deemed unnecessary.

Get a list of topologies

To get a JSON with the Knox topologies, use the following command:

$ curl -iu <login>:<password> -H "Accept: application/json" -X GET https://<gateway-host>/gateway/admin/api/v1/topologies

The output should be similar to:

HTTP/1.1 200 OK
Date: Thu, 10 Oct 2024 21:28:25 GMT
Content-Type: application/json
Content-Length: 1190

{
   "topologies" : {
      "topology" : [ {
         "name" : "admin",
         "timestamp" : "1728594886988",
         "uri" : "https://10.92.40.58:8443/gateway/admin",
         "href" : "https://10.92.40.58:8443/gateway/manager/api/v1/topologies/admin"
      }, {
         "name" : "homepage",
         "timestamp" : "1579705815000",
         "uri" : "https://10.92.40.58:8443/gateway/homepage",
         "href" : "https://10.92.40.58:8443/gateway/manager/api/v1/topologies/homepage"
      }, {
         "name" : "knoxsso",
         "timestamp" : "1728594887604",
         "uri" : "https://10.92.40.58:8443/gateway/knoxsso",
         "href" : "https://10.92.40.58:8443/gateway/manager/api/v1/topologies/knoxsso"
      }, {
         "name" : "manager",
         "timestamp" : "1728594888074",
         "uri" : "https://10.92.40.58:8443/gateway/manager",
         "href" : "https://10.92.40.58:8443/gateway/manager/api/v1/topologies/manager"
      }, {
         "name" : "metadata",
         "timestamp" : "1728594888537",
         "uri" : "https://10.92.40.58:8443/gateway/metadata",
         "href" : "https://10.92.40.58:8443/gateway/manager/api/v1/topologies/metadata"
      } ]
   }
}

Add a topology

To manually add a topology, use the corresponding PUT request:

$ curl -iu <login>:<password> -H "Content-Type: application/xml" -d '<xml>' -X PUT https://<gateway-host>/gateway/admin/api/v1/topologies/test-topology

You will receive the contents of the XML file as an output of this command. To check that the topology was created, you can refer to the Knox Admin UI.

A new Knox topology
A new Knox topology
A new Knox topology
A new Knox topology
Found a mistake? Seleсt text and press Ctrl+Enter to report it