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 isDELETEorGET. -
<request_type>— type of the HTTP request (GET,POST,PUT,DELETE). If the request type isDELETE, remove the-Hparameter 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/topologiesThe 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-topologyYou 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.
