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": []
  }