Apache Knox Admin REST API
The Knox Admin REST API provides endpoints for topology management, service descriptor management, provider configuration, and version information for administering the Knox gateway.
OpenAPI Specification
openapi: 3.0.3
info:
title: Apache Knox Admin REST API
description: REST API for Apache Knox gateway administration including topology management, service discovery, token management, and audit operations.
version: 2.0.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
contact:
email: user@knox.apache.org
servers:
- url: https://localhost:8443/gateway/admin
description: Apache Knox Admin API
security:
- basicAuth: []
tags:
- name: Topologies
description: Gateway topology management
- name: Services
description: Backend service management
- name: Tokens
description: Knox token management
- name: Descriptors
description: Simple descriptor management
- name: Providers
description: Provider configuration management
paths:
/api/v1/topologies:
get:
operationId: listTopologies
summary: Apache knox Apache Knox List Topologies
description: List all configured gateway topologies.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
responses:
'200':
description: List of topologies
content:
application/json:
schema:
$ref: '#/components/schemas/TopologyList'
examples:
listTopologies200Example:
summary: Default listTopologies 200 response
x-microcks-default: true
value:
topologies: {}
post:
operationId: createTopology
summary: Apache knox Apache Knox Create Topology
description: Create or update a gateway topology.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Topology'
examples:
createTopologyRequestExample:
summary: Default createTopology request
x-microcks-default: true
value:
name: sandbox
uri: https://localhost:8443/gateway/sandbox
timestamp: 1718153645993
responses:
'200':
description: Topology created or updated
/api/v1/topologies/{topologyName}:
get:
operationId: getTopology
summary: Apache knox Apache Knox Get Topology
description: Get details of a specific topology.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: topologyName
in: path
required: true
schema:
type: string
example: sandbox
responses:
'200':
description: Topology details
content:
application/json:
schema:
$ref: '#/components/schemas/Topology'
examples:
getTopology200Example:
summary: Default getTopology 200 response
x-microcks-default: true
value:
name: sandbox
uri: https://localhost:8443/gateway/sandbox
timestamp: 1718153645993
'404':
description: Topology not found
delete:
operationId: deleteTopology
summary: Apache knox Apache Knox Delete Topology
description: Delete a gateway topology.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: topologyName
in: path
required: true
schema:
type: string
example: sandbox
responses:
'200':
description: Topology deleted
/api/v1/topologies/{topologyName}/urls:
get:
operationId: getTopologyUrls
summary: Apache knox Apache Knox Get Topology URLs
description: Get all service URLs for a topology.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: topologyName
in: path
required: true
schema:
type: string
example: sandbox
responses:
'200':
description: Topology service URLs
content:
application/json:
schema:
type: array
items:
type: string
examples:
getTopologyUrls200Example:
summary: Default getTopologyUrls 200 response
x-microcks-default: true
value: {}
/api/v1/version:
get:
operationId: getVersion
summary: Apache knox Apache Knox Get Version
description: Get the Knox gateway version information.
tags: [Topologies]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
responses:
'200':
description: Knox version
content:
application/json:
schema:
$ref: '#/components/schemas/KnoxVersion'
examples:
getVersion200Example:
summary: Default getVersion 200 response
x-microcks-default: true
value:
version: 2.0.0
hash: abc123def
/api/v1/descriptors:
get:
operationId: listDescriptors
summary: Apache knox Apache Knox List Descriptors
description: List all simple descriptors on the gateway.
tags: [Descriptors]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
responses:
'200':
description: List of descriptors
content:
application/json:
schema:
$ref: '#/components/schemas/DescriptorList'
examples:
listDescriptors200Example:
summary: Default listDescriptors 200 response
x-microcks-default: true
value:
descriptors: []
post:
operationId: createDescriptor
summary: Apache knox Apache Knox Create Descriptor
description: Create a new simple descriptor.
tags: [Descriptors]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Descriptor'
examples:
createDescriptorRequestExample:
summary: Default createDescriptor request
x-microcks-default: true
value:
name: hadoop-cluster
discoveryType: Ambari
discoveryAddress: http://ambari:8080
cluster: my-cluster
providerConfig: my-provider-config
services: []
responses:
'200':
description: Descriptor created
/api/v1/descriptors/{descriptorName}:
get:
operationId: getDescriptor
summary: Apache knox Apache Knox Get Descriptor
description: Get a specific simple descriptor.
tags: [Descriptors]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: descriptorName
in: path
required: true
schema:
type: string
example: hadoop-cluster
responses:
'200':
description: Descriptor details
delete:
operationId: deleteDescriptor
summary: Apache knox Apache Knox Delete Descriptor
description: Delete a simple descriptor.
tags: [Descriptors]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
parameters:
- name: descriptorName
in: path
required: true
schema:
type: string
example: hadoop-cluster
responses:
'200':
description: Descriptor deleted
/api/v1/providerconfig:
get:
operationId: listProviderConfigs
summary: Apache knox Apache Knox List Provider Configs
description: List all provider configurations.
tags: [Providers]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
responses:
'200':
description: List of provider configurations
post:
operationId: createProviderConfig
summary: Apache knox Apache Knox Create Provider Config
description: Create a new provider configuration.
tags: [Providers]
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
requestBody:
required: true
content:
application/json:
schema:
type: object
examples:
createProviderConfigRequestExample:
summary: Default createProviderConfig request
x-microcks-default: true
value: {}
responses:
'200':
description: Provider config created
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
schemas:
TopologyList:
type: object
description: List of Knox topologies
properties:
topologies:
type: object
properties:
topology:
type: array
items:
$ref: '#/components/schemas/Topology'
Topology:
type: object
description: A Knox gateway topology
properties:
name:
type: string
description: Topology name
example: sandbox
uri:
type: string
description: Topology gateway URL
example: https://localhost:8443/gateway/sandbox
timestamp:
type: integer
description: Last modified timestamp
example: 1718153645993
KnoxVersion:
type: object
description: Knox gateway version information
properties:
version:
type: string
description: Knox version string
example: 2.0.0
hash:
type: string
description: Build hash
example: abc123def
DescriptorList:
type: object
description: List of simple descriptors
properties:
descriptors:
type: array
items:
$ref: '#/components/schemas/Descriptor'
Descriptor:
type: object
description: A Knox simple descriptor
properties:
name:
type: string
description: Descriptor name
example: hadoop-cluster
discoveryType:
type: string
description: Service discovery type
example: Ambari
discoveryAddress:
type: string
description: Discovery service address
example: http://ambari:8080
cluster:
type: string
description: Cluster name
example: my-cluster
providerConfig:
type: string
description: Referenced provider configuration
example: my-provider-config
services:
type: array
description: Services exposed by this descriptor
items:
type: object