Provisioning REST API


Overview 

The Connection State API offers functionalities to manage and update Kafka connection states within our software suite, providing a seamless experience for system integrators and developers alike.

Endpoint: Update Connections State 

Endpoint Details: 

  • URI: /api/v1/state/connections
  • Method: PUT

Description: 

This endpoint allows users to update connection states within our system.

Parameters: 

  1. validateOnly (boolean):

    • Description: If set, the request will only validate the provided configurations without applying any actual changes.
    • Default: false.
  2. validateConnectivity (boolean):

    • Description: Determines if a connectivity test should be executed as part of the validation procedure.
    • Default: true.

Request Structure: 

The request format is multipart/form-data with two main parts:

  • provisioning:

    • Content-Type: text/plain; charset=utf-8
    • Description: A YAML-based manifest detailing desired connection states for various services such as Kafka, Confluent Schema Registry, Elasticsearch, and more.
  • attachedFile:

    • Content-Type: application/octet-stream
    • Description: Here, users can attach essential files to facilitate connections. The filename acts as a reference in the provisioning manifest.

Provisioning Manifest 

In your provisioning manifest, you’ll define the configuration for your connections. As an example, the Kafka connection can be defined as follows:

kafka:
  - name: kafka
    version: 1
    tags:
      - primary
      - production
    configuration:
      protocol:
        value: SASL_SSL
      sslKeystore:
        file: "keystoreFile"
      sslKeystorePassword:
        value: "keystore_password"
      kafkaBootstrapServers:
        value:
          - "sasl-ssl://broker1.example.com:9092"
          - "sasl-ssl://broker2.example.com:9092"
      saslMechanism:
        value: "GSSAPI"
      metricsPort:
        value: 7091
      metricsUsername:
        value: "metricsUser"
      metricsPassword:
        value: "metricsPass123"
      metricsType:
        value: "JMX"
      additionalProperties:
        value:
          client.id: "my-producer"
      metricsCustomUrlMappings:
        value:
          broker1.example.com: "http://metrics.broker1.example.com"
          broker2.example.com: "http://metrics.broker2.example.com"
aws:
  - name: AWSCluster
    version: 1
    tags:
      - main
      - registrySupport
    configuration:
      accessKeyId: "YOUR_AWS_ACCESS_KEY"
      secretAccessKey: "YOUR_AWS_SECRET"
      region: "us-west-1"

awsGlueSchemaRegistry:
  - name: schema-registry
    version: 1
    tags:
      - production
    configuration:
      accessKeyId:
        reference: "AWSCluster"
      secretAccessKey:
        reference: "AWSCluster"
      glueRegistryArn:
        value: "arn:aws:glue:zone:id:registry/registry_name"

In this example:

  • The sslKeystore from the Kafka connection is a file that is attached to the request as keystoreFile.
  • The awsGlueSchemaRegistry connection’s accessKeyId and secretAccessKey are references to the aws connection’s accessKeyId and secretAccessKey respectively. This allows you to reuse the same credentials for multiple services.

For a comprehensive list of all supported properties for each connection type, refer to the detailed OpenAPI specification.

Sample Request: 

curl -X PUT "https://api.yourproductdomain.com/api/v1/state/connections?validateOnly=true&validateConnectivity=true" \
    --header "X-Kafka-Lenses-Token: ${LENSES_SESSION_TOKEN}" \
    --header 'Content-Type: multipart/form-data' \
    --header 'Content-Disposition: form-data;' \
    --form "provisioning=@/path_to_config/config.yaml;type=text/plain(utf-8)" \
    -F "keystoreFile=@/path_to_file/file.extension;type=application/octet-stream"

Expected Responses: 

  • 200 OK: The request was successful, and the connection state has been updated. You’d receive a response detailing the updated, created, and deleted references.

    Sample Response:

    {
      "updated": ["Kafka_MainCluster", "ElasticSearch_MainCluster"],
      "created": ["Confluent_MainCluster"],
      "deleted": ["Kafka_OldCluster"]
    }
    
  • 400 Bad Request: The request was incorrect. Details about the exact issue will be provided in the response. For instance, missing required fields or invalid values can trigger this response.

    Sample Response:

    {
      "fields": [
          {"field": "kafkaBootstrapServers", "error": "Field is required"}
      ],
      "error": "There was an error processing your request.",
      "nonFieldErrors": []
    }
    

Endpoint: Retrieve System State 

Endpoint Details: 

  • URI: /api/v1/state
  • Method: GET

Description: 

This endpoint allows users to retrieve the current system state, which includes license details and connections.

Expected Responses: 

  • 200 OK: Successfully retrieves the system state.

    Sample Response:

    {
      "license": {
        "maxBrokers": 5,
        "expiry": 1672531199000,
        "clientId": "client123",
        "isRespected": true,
        "status": "Valid"
      },
      "connections": {
        "Kafka": [{
          "name": "kafka",
          "version": 1,
          "tags": ["primary", "production"]
        }],
        "ElasticSearch": [...]
        // ... other connection types
      }
    }
    

Endpoint: Update License Data 

Endpoint Details: 

  • URI: /api/v1/state/license
  • Method: PUT

Description: 

This endpoint allows users to update the license data for the system, ensuring compliance with the purchased package and accessing specific functionalities.

Request Structure: 

The request should contain a JSON payload detailing the license information, including the source, client ID, details, and the key.

Sample Request: 

curl -X PUT "https://api.yourproductdomain.com/api/v1/state/license" \
     -H "Content-Type: application/json" \
     -d '{
         "source": "license_source",
         "clientId": "client_123",
         "details": "license_details",
         "key": "license_key_abc123"
     }'

Expected Responses: 

  • 200 OK: The license was successfully updated, and the current license info is returned.

    Sample Response:

    {
      "maxBrokers": 10,
      "expiry": 1672531199000,
      "clientId": "client123",
      "isRespected": true,
      "status": "Valid",
      "settings": {
        "security": {
          "root": { "enabled": true }
          // ... other security settings
        }
        // ... other settings
      },
      "currentTime": 1672527599000
    }
    
  • 400 Bad Request: The request was incorrect. Information about the precise problem will be provided in the response.

    Sample Response:

    {
      "fields": [
          {"field": "key", "error": "Invalid key provided"}
      ],
      "error": "There was an error processing your license update request.",
      "nonFieldErrors": []
    }
    
--
Last modified: April 8, 2024