Apache Knox

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.

GitHub OpenAPI

Documentation

📖
Documentation
https://knox.apache.org/books/knox-2-0-0/user-guide.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/apache-knox/refs/heads/main/openapi/apache-knox-admin-api.yaml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/apache-knox/refs/heads/main/capabilities/admin-descriptors.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/apache-knox/refs/heads/main/capabilities/admin-providers.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/apache-knox/refs/heads/main/capabilities/admin-topologies.yaml

OpenAPI Specification

apache-knox-admin-api.yaml Raw ↑ 
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: [email protected]
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