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 isDELETE
orGET
. -
<request_type>
— type of the HTTP request (GET
,POST
,PUT
,DELETE
). If the request type isDELETE
, 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.

