Skip to content

Admin API

Admin API

Access to the administrator functions of Knox are provided by the Admin REST API.

Admin API URL

The URL mapping for the Knox Admin API is:

Resource URL
GatewayAPI https://{gateway-host}:{gateway-port}/{gateway-path}/admin/api/v1

Please note that to access this API, the user attempting to connect must have admin credentials configured on the LDAP Server

API Documentation
Resource Operation Description
version GET Get the gateway version and the associated version hash
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/version -H Accept:application/json
  Example Response 
{
  "ServerVersion" : {
    "version" : "VERSION_ID",
    "hash" : "VERSION_HASH"
  }
}
topologies GET Get an enumeration of the topologies currently deployed in the gateway.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/topologies -H Accept:application/json
  Example Response 
{
   "topologies" : {
      "topology" : [ {
         "name" : "admin",
         "timestamp" : "1501508536000",
         "uri" : "https://localhost:8443/gateway/admin",
         "href" : "https://localhost:8443/gateway/admin/api/v1/topologies/admin"
      }, {
         "name" : "sandbox",
         "timestamp" : "1501508536000",
         "uri" : "https://localhost:8443/gateway/sandbox",
         "href" : "https://localhost:8443/gateway/admin/api/v1/topologies/sandbox"
      } ]
   }
}
topologies/{id} GET Get a JSON representation of the specified topology
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/topologies/admin -H Accept:application/json
  Example Response 
{
  "name": "admin",
  "providers": [{
    "enabled": true,
    "name": "ShiroProvider",
    "params": {
      "sessionTimeout": "30",
      "main.ldapRealm": "org.apache.knox.gateway.shirorealm.KnoxLdapRealm",
      "main.ldapRealm.userDnTemplate": "uid={0},ou=people,dc=hadoop,dc=apache,dc=org",
      "main.ldapRealm.contextFactory.url": "ldap://localhost:33389",
      "main.ldapRealm.contextFactory.authenticationMechanism": "simple",
      "urls./**": "authcBasic"
    },
    "role": "authentication"
  }, {
    "enabled": true,
    "name": "AclsAuthz",
    "params": {
      "knox.acl": "admin;*;*"
    },
    "role": "authorization"
  }, {
    "enabled": true,
    "name": "Default",
    "params": {},
    "role": "identity-assertion"
  }, {
    "enabled": true,
    "name": "static",
    "params": {
      "localhost": "sandbox,sandbox.hortonworks.com"
    },
    "role": "hostmap"
  }],
  "services": [{
      "name": null,
      "params": {},
      "role": "KNOX",
      "url": null
  }],
  "timestamp": 1406672646000,
  "uri": "https://localhost:8443/gateway/admin"
}
  PUT Add (and deploy) a topology
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/topologies/mytopology \
     -X PUT \
     -H Content-Type:application/xml
     -d "@mytopology.xml"
  Example Response 
<?xml version="1.0" encoding="UTF-8"?>
<topology>
   <uri>https://localhost:8443/gateway/mytopology</uri>
   <name>mytopology</name>
   <timestamp>1509720338000</timestamp>
   <gateway>
      <provider>
         <role>authentication</role>
         <name>ShiroProvider</name>
         <enabled>true</enabled>
         <param>
            <name>sessionTimeout</name>
            <value>30</value>
         </param>
         <param>
            <name>main.ldapRealm</name>
            <value>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</value>
         </param>
         <param>
            <name>main.ldapContextFactory</name>
            <value>org.apache.knox.gateway.shirorealm.KnoxLdapContextFactory</value>
         </param>
         <param>
            <name>main.ldapRealm.contextFactory</name>
            <value>$ldapContextFactory</value>
         </param>
         <param>
            <name>main.ldapRealm.userDnTemplate</name>
            <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
         </param>
         <param>
            <name>main.ldapRealm.contextFactory.url</name>
            <value>ldap://localhost:33389</value>
         </param>
         <param>
            <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
            <value>simple</value>
         </param>
         <param>
            <name>urls./**</name>
            <value>authcBasic</value>
         </param>
      </provider>
      <provider>
         <role>identity-assertion</role>
         <name>Default</name>
         <enabled>true</enabled>
      </provider>
      <provider>
         <role>hostmap</role>
         <name>static</name>
         <enabled>true</enabled>
         <param>
            <name>localhost</name>
            <value>sandbox,sandbox.hortonworks.com</value>
         </param>
      </provider>
   </gateway>
   <service>
      <role>NAMENODE</role>
      <url>hdfs://localhost:8020</url>
   </service>
   <service>
      <role>JOBTRACKER</role>
      <url>rpc://localhost:8050</url>
   </service>
   <service>
      <role>WEBHDFS</role>
      <url>http://localhost:50070/webhdfs</url>
   </service>
   <service>
      <role>WEBHCAT</role>
      <url>http://localhost:50111/templeton</url>
   </service>
   <service>
      <role>OOZIE</role>
      <url>http://localhost:11000/oozie</url>
   </service>
   <service>
      <role>WEBHBASE</role>
      <url>http://localhost:60080</url>
   </service>
   <service>
      <role>HIVE</role>
      <url>http://localhost:10001/cliservice</url>
   </service>
   <service>
      <role>RESOURCEMANAGER</role>
      <url>http://localhost:8088/ws</url>
   </service>
</topology>
  DELETE Delete (and undeploy) a topology
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/topologies/mytopology -X DELETE
  Example Response 
{ "deleted" : true }
providerconfig GET Get an enumeration of the shared provider configurations currently deployed to the gateway.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/providerconfig
  Example Response 
{
  "href" : "https://localhost:8443/gateway/admin/api/v1/providerconfig",
  "items" : [ {
    "href" : "https://localhost:8443/gateway/admin/api/v1/providerconfig/myproviders",
    "name" : "myproviders.xml"
  },{
   "href" : "https://localhost:8443/gateway/admin/api/v1/providerconfig/sandbox-providers",
   "name" : "sandbox-providers.xml"
  } ]
}
providerconfig/{id} GET Get the XML content of the specified shared provider configuration.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/providerconfig/sandbox-providers \
     -H Accept:application/xml
  Example Response 
<gateway>
    <provider>
        <role>authentication</role>
        <name>ShiroProvider</name>
        <enabled>true</enabled>
        <param>
            <name>sessionTimeout</name>
            <value>30</value>
        </param>
        <param>
            <name>main.ldapRealm</name>
            <value>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</value>
        </param>
        <param>
            <name>main.ldapContextFactory</name>
            <value>org.apache.knox.gateway.shirorealm.KnoxLdapContextFactory</value>
        </param>
        <param>
            <name>main.ldapRealm.contextFactory</name>
            <value>$ldapContextFactory</value>
        </param>
        <param>
            <name>main.ldapRealm.userDnTemplate</name>
            <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
        </param>
        <param>
            <name>main.ldapRealm.contextFactory.url</name>
            <value>ldap://localhost:33389</value>
        </param>
        <param>
            <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
            <value>simple</value>
        </param>
        <param>
            <name>urls./**</name>
            <value>authcBasic</value>
        </param>
    </provider>

    <provider>
        <role>identity-assertion</role>
        <name>Default</name>
        <enabled>true</enabled>
    </provider>

    <provider>
        <role>hostmap</role>
        <name>static</name>
        <enabled>true</enabled>
        <param>
            <name>localhost</name>
            <value>sandbox,sandbox.hortonworks.com</value>
        </param>
    </provider>
</gateway>
  PUT Add a shared provider configuration.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/providerconfig/sandbox-providers \
     -X PUT \ 
     -H Content-Type:application/xml \
     -d "@sandbox-providers.xml"
  Example Response 
HTTP 201 Created
  DELETE Delete a shared provider configuration
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/providerconfig/sandbox-providers -X DELETE
  Example Response 
{ "deleted" : "provider config sandbox-providers" }
descriptors GET Get an enumeration of the simple descriptors currently deployed to the gateway.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/descriptors -H Accept:application/json
  Example Response 
{
   "href" : "https://localhost:8443/gateway/admin/api/v1/descriptors",
   "items" : [ {
      "href" : "https://localhost:8443/gateway/admin/api/v1/descriptors/docker-sandbox",
      "name" : "docker-sandbox.json"
   }, {
      "href" : "https://localhost:8443/gateway/admin/api/v1/descriptors/mytopology",
      "name" : "mytopology.yml"
   } ]
}
descriptors/{id} GET Get the content of the specified descriptor.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/descriptors/docker-sandbox \
     -H Accept:application/json
  Example Response 
{
  "discovery-type":"AMBARI",
  "discovery-address":"http://sandbox.hortonworks.com:8080",
  "provider-config-ref":"sandbox-providers",
  "cluster":"Sandbox",
  "services":[
    {"name":"NAMENODE"},
    {"name":"JOBTRACKER"},
    {"name":"WEBHDFS"},
    {"name":"WEBHCAT"},
    {"name":"OOZIE"},
    {"name":"WEBHBASE"},
    {"name":"HIVE"},
    {"name":"RESOURCEMANAGER"} ]
}
  PUT Add a simple descriptor (and generate and deploy a full topology descriptor).
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/descriptors/docker-sandbox \
     -X PUT \
     -H Content-Type:application/json \
     -d "@docker-sandbox.json"
  Example Response 
HTTP 201 Created
  DELETE Delete a simple descriptor (and undeploy the associated topology)
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/descriptors/docker-sandbox -X DELETE
  Example Response 
{ "deleted" : "descriptor docker-sandbox" }
aliases/{topology} GET Get the aliases associated with the specified topology.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/aliases/sandbox
  Example Response 
{
  "topology":"sandbox",
  "aliases":["myalias","encryptquerystring"]
}
aliases/{topology}/{alias} PUT Add the specified alias for the specified topology.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/aliases/sandbox/putalias -X PUT \
     -H "Content-Type: application/json" \
     -d "value=mysecret"
  Example Response 
{
  "created" : {
    "topology": "sandbox",
    "alias": "putalias"
  }
}
  POST Add the specified alias for the specified topology.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/aliases/sandbox/postalias -X POST \
     -H "Content-Type: application/json" \
     -d "value=mysecret"
  Example Response 
{
  "created" : {
    "topology": "sandbox",
    "alias": "postalias"
  }
}
  DELETE Remove the specified alias for the specified topology.
  Example Request 
curl -iku admin:admin-password {GatewayAPI}/aliases/sandbox/myalias -X DELETE
  Example Response 
{
  "deleted" : {
    "topology": "sandbox",
    "alias": "myalias"
  }
}