openapi: 3.0.0
info:
  contact:
    email: support@tyk.io
    name: Tyk Technologies
    url: https://tyk.io/contact
  version: 1.0.0
  title: MDCB Data Planes and Diagnostics API
  description: >
    This API provides operations for monitoring Data Planes connected to MDCB and accessing diagnostic data. 
    It includes endpoints for retrieving connected data plane details, performing health checks, 
    and accessing Go's built-in pprof diagnostics for advanced performance profiling.
tags:
  - name: Data Planes
    description: Operations related to data plane management and information
  - name: Health
    description: Endpoints for checking system health and status
  - name: Debug
    description: Diagnostic and profiling endpoints
  - name: Configuration
    description: Configuration and environment variable management
servers:
  - url: https://{tenant}
    variables:
      tenant:
        default: localhost:8181
        description: Your MDCB host
security:
  - api_key: []
paths:
  /dataplanes:
    get:
      tags:
        - Data Planes
      summary: Retrieve information of all the connected data plane nodes.
      description: Provides a list of all the data plane nodes connected to MDCB. Data plane nodes are Tyk Gateways that make your APIs available to your consumers. MDCB offers centralised management of your data plane nodes. This endpoint offers metadata and status for all connected data plane nodes, allowing for monitoring and troubleshooting.
      operationId: dataplanesGet
      parameters:
        - in: header
          name: x-tyk-authorization
          description: Secret value set in sink.conf
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful retrieval of the connected data planes.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: "#/components/schemas/Node"
        "401":
          description: Forbidden access due to invalid or missing administrative key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /health:
    get:
      tags:
        - Health
      summary: Health Check
      description: Returns OK if the service is up and running.
      operationId: healthGet
      responses:
        "200":
          description: Service is up and running.
          content:
            text/plain:
              schema:
                type: string
                example: "OK"
  /readiness:
    get:
      tags:
        - Health
      summary: Check system readiness status
      description: >
        Assesses the readiness of the system and its critical components.
        This endpoint determines if the system is prepared to handle requests
        by evaluating the status of essential services and dependencies.
      operationId: readinessGet
      responses:
        "200":
          description: >
            System is ready. All critical components are operational and 
            the system is capable of handling requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadinessStatus"
        "503":
          description: >
            System is not ready. One or more critical components are 
            non-operational, preventing the system from handling requests properly.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadinessFailure"
  /liveness:
    get:
      tags:
        - Health
      summary: Check liveness status
      description: Provides the liveness status of the service.
      operationId: livenessGet
      responses:
        "200":
          description: MDCB is alive.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LivenessStatus"
  /debug/pprof/profile:
    get:
      tags:
        - Debug
      summary: CPU Profiling data
      description: Returns CPU profiling data. Available only when HTTPProfile is enabled in sink.conf.
      operationId: debugPprofProfileGet
      responses:
        "200":
          description: CPU profiling data.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /debug/pprof/{profileType}:
    get:
      tags:
        - Debug
      summary: pprof data
      description: >
        Serves various pprof data like heap, goroutine, threadcreate, block, and so on. The `{profileType}` path parameter can accept various profiling types as well as more complex patterns. Available only when HTTPProfile is enabled in sink.conf.
      operationId: debugPprofProfileTypeGet
      parameters:
        - in: path
          name: profileType
          required: true
          description: The specific pprof data to retrieve (heap, goroutine, threadcreate, block, etc.), or a pattern matching multiple types.
          schema:
            type: string
            example: heap
      responses:
        "200":
          description: pprof data.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /config:
    get:
      tags:
        - Configuration
      summary: Retrieve current configuration status
      description: |
        Returns the current configuration status of the system. You can optionally filter for a specific configuration field.

        **Example curl commands:**

        Get full configuration:
        ```bash
        curl -X GET \
        http://localhost:8181/config \
        -H 'X-Tyk-Authorization: your-secret-key'
        ```

        Get specific configuration field:
        ```bash
        curl -X GET \
        'http://localhost:8181/config?field=storage.host' \
        -H 'X-Tyk-Authorization: your-secret-key'
        ```
      operationId: configGet
      parameters:
        - in: header
          name: X-Tyk-Authorization
          description: Secret value set in sink.conf
          required: true
          schema:
            type: string
          example: "your-secret-key"
        - in: query
          name: field
          description: Optional configuration field name to filter by
          required: false
          schema:
            type: string
          example: "storage.host"
      responses:
        "200":
          description: Successful retrieval of the current configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum: ["full", "single"]
                discriminator:
                  propertyName: type
                allOf:
                  - $ref: "#/components/schemas/ConfigStatus"
                  - $ref: "#/components/schemas/EnvVariable"
              examples:
                full_config:
                  summary: Full configuration
                  value:
                    type: "full"
                    listen_port: 9090
                    healthcheck_port: 8180
                    http_port: 8180
                    enable_http_profiler: false
                    server_options:
                      use_ssl: false
                      certificate:
                        cert_file: "./server.crt"
                        key_file: "./server.key"
                      min_version: 0
                      ssl_ciphers: null
                      ssl_certificates: null
                    http_server_options:
                      use_ssl: false
                      certificate:
                        cert_file: ""
                        key_file: ""
                      min_version: 0
                      ssl_ciphers: null
                      ssl_certificates: null
                    security:
                      private_certificate_encoding_secret: ""
                      enable_http_secure_endpoints: true
                      secret: ""
                    storage:
                      type: "redis"
                      host: "localhost"
                      port: 6379
                      master_name: ""
                      sentinel_password: ""
                      username: ""
                      password: ""
                      database: 0
                      optimisation_max_idle: 0
                      optimisation_max_active: 0
                      enable_cluster: false
                      hosts: null
                      addrs: null
                      redis_use_ssl: false
                      redis_ssl_insecure_skip_verify: false
                      debug: false
                      timeout: 0
                      use_ssl: false
                      ssl_insecure_skip_verify: false
                      ca_file: ""
                      cert_file: ""
                      key_file: ""
                      max_version: ""
                      min_version: ""
                    analytics:
                      type: "mongo"
                      connection_string: ""
                      table_sharding: false
                      batch_size: 0
                      postgres:
                        prefer_simple_protocol: false
                      mysql:
                        default_string_size: 0
                        disable_datetime_precision: false
                        dont_support_rename_index: false
                        dont_support_rename_column: false
                        skip_initialize_with_version: false
                      mongo_url: ""
                      mongo_use_ssl: false
                      mongo_ssl_insecure_skip_verify: false
                      mongo_ssl_allow_invalid_hostnames: false
                      mongo_ssl_ca_file: ""
                      mongo_ssl_pem_keyfile: ""
                      mongo_session_consistency: ""
                      mongo_batch_size: 0
                      driver: "mongo-go"
                      mongo_direct_connection: false
                    hash_keys: true
                    session_timeout: 0
                    forward_analytics_to_pump: false
                    enable_multiple_analytics_keys: false
                    dont_store_selective: false
                    dont_store_aggregate: false
                    org_session_expiration: 60
                    org_session_cleanup: 60
                    license: ""
                    aggregates_ignore_tags: null
                    track_all_paths: false
                    store_analytics_per_minute: false
                    ignore_tag_prefix_list: null
                    threshold_len_tag_list: 1000
                    omit_analytics_index_creation: false
                    enable_separate_analytics_store: false
                    analytics_storage:
                      type: ""
                      host: ""
                      port: 0
                      master_name: ""
                      sentinel_password: ""
                      username: ""
                      password: ""
                      database: 0
                      optimisation_max_idle: 0
                      optimisation_max_active: 0
                      enable_cluster: false
                      hosts: null
                      addrs: null
                      redis_use_ssl: false
                      redis_ssl_insecure_skip_verify: false
                      debug: false
                      timeout: 0
                      use_ssl: false
                      ssl_insecure_skip_verify: false
                      ca_file: ""
                      cert_file: ""
                      key_file: ""
                      max_version: ""
                      min_version: ""
                    log_level: "info"
                    enable_key_logging: false
                    sync_worker_config:
                      enabled: true
                      hash_keys: true
                      max_batch_size: 1000
                      time_between_batches: 3
                      max_workers: 1000
                      warmup_time: 0
                      group_key_ttl: 30
                    enable_ownership: false
                single_field:
                  summary: Single configuration field (filtered by query parameter)
                  value:
                    type: "single"
                    config_field: "sync_worker_config.warmup_time"
                    env: "TYK_MDCB_SYNCWORKERCONFIG_WARMUPTIME"
                    value: "0"
                    obfuscated: false
        "400":
          description: Field not found in configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "field not found"
        "401":
          description: Forbidden access due to invalid or missing administrative key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /env:
    get:
      tags:
        - Configuration
      summary: Retrieve environment variables
      description: |
        Returns environment variables of the system. You can optionally filter for a specific configuration field.

        **Example curl commands:**

        Get all environment variables:
        ```bash
        curl -X GET \ 
        http://localhost:8181/env \
        -H 'X-Tyk-Authorization: your-secret-key'
        ```

        Get specific environment variable:
        ```bash
        curl -X GET \
        'http://localhost:8181/env?env=TYK_MDCB_SYNCWORKERCONFIG_WARMUPTIME' \
        -H 'X-Tyk-Authorization: your-secret-key'
        ```
      operationId: envGet
      parameters:
        - in: header
          name: X-Tyk-Authorization
          description: Secret value set in sink.conf
          required: true
          schema:
            type: string
          example: "your-secret-key"
        - in: query
          name: env
          description: Optional environment variable name to filter by
          required: false
          schema:
            type: string
          example: "TYK_MDCB_SYNCWORKERCONFIG_WARMUPTIME"
      responses:
        "200":
          description: Successful retrieval of environment variables.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      type: string
                  - $ref: "#/components/schemas/EnvVariable"
              examples:
                array_response:
                  summary: All environment variables
                  value:
                    - "TYK_MDCB_ANALYTICSSTORAGE_SSLINSECURESKIPVERIFY=false"
                    - "TYK_MDCB_STORAGE_HOST=localhost"
                    - "TYK_MDCB_LISTENPORT=9090"
                single_variable:
                  summary: Single environment variable (filtered by query parameter)
                  value:
                    config_field: "sync_worker_config.warmup_time"
                    env: "TYK_MDCB_SYNCWORKERCONFIG_WARMUPTIME"
                    value: "0"
                    obfuscated: false
        "400":
          description: Environment variable not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "environment variable not found"
        "401":
          description: Forbidden access due to invalid or missing administrative key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Node:
      type: object
      properties:
        node_id:
          type: string
          example: "solo-uid"
        api_key:
          type: string
          example: "c5e9b9ed8dee42fb668f81cef7f905bb"
        group_id:
          type: string
          example: "Redis Cluster Slave 1"
        node_version:
          type: string
          example: "v5.3.0-dev"
        ttl:
          type: integer
          example: 10
        tags:
          type: array
          items:
            type: string
          example: ["tag1", "tag2"]
        health:
          $ref: "#/components/schemas/Health"
        stats:
          $ref: "#/components/schemas/Stats"
        host_details:
          $ref: "#/components/schemas/HostDetails"
    Health:
      type: object
      properties:
        redis:
          $ref: "#/components/schemas/ComponentStatus"
        rpc:
          $ref: "#/components/schemas/ComponentStatus"
    ComponentStatus:
      type: object
      properties:
        status:
          type: string
          example: "pass"
        componentType:
          type: string
          example: "datastore"
        time:
          type: string
          format: date-time
          example: "2024-02-23T08:51:23-03:00"
    Stats:
      type: object
      properties:
        apis_count:
          type: integer
          example: 1
        policies_count:
          type: integer
          example: 0
    HostDetails:
      type: object
      properties:
        Hostname:
          type: string
          example: "Peter-MacBook-Pro.local"
        PID:
          type: integer
          example: 62663
        Address:
          type: string
          example: "203.0.113.0"
    ReadinessStatus:
      type: object
      properties:
        status:
          type: string
          example: "pass"
        status_code:
          type: integer
          example: 200
        components:
          type: array
          items:
            $ref: "#/components/schemas/ComponentReadiness"
    ReadinessFailure:
      type: object
      properties:
        status:
          type: string
          example: "fail"
        status_code:
          type: integer
          example: 503
        components:
          type: array
          items:
            $ref: "#/components/schemas/ComponentReadinessFailure"
    ComponentReadiness:
      type: object
      properties:
        name:
          type: string
          example: "postgres"
        status:
          type: string
          example: "pass"
        observation_ts:
          type: string
          format: date-time
          example: "2024-07-29T13:58:56.699052-04:00"
    ComponentReadinessFailure:
      type: object
      properties:
        name:
          type: string
          example: "postgres"
        status:
          type: string
          example: "fail"
        observation_ts:
          type: string
          format: date-time
          example: "2024-07-29T13:58:56.699052-04:00"
    LivenessStatus:
      type: object
      properties:
        status:
          type: string
          example: "pass"
        status_code:
          type: integer
          example: 200
    Error:
      type: object
      properties:
        error:
          type: string
          example: "Attempted administrative access with invalid or missing key!"
    ConfigStatus:
      type: object
      properties:
        listen_port:
          type: integer
          example: 9090
        healthcheck_port:
          type: integer
          example: 8180
        http_port:
          type: integer
          example: 8180
        enable_http_profiler:
          type: boolean
          example: false
        server_options:
          type: object
          properties:
            use_ssl:
              type: boolean
              example: false
            certificate:
              type: object
              properties:
                cert_file:
                  type: string
                  example: "./server.crt"
                key_file:
                  type: string
                  example: "./server.key"
            min_version:
              type: integer
              example: 0
            ssl_ciphers:
              type: string
              nullable: true
            ssl_certificates:
              type: string
              nullable: true
        http_server_options:
          type: object
          properties:
            use_ssl:
              type: boolean
              example: false
            certificate:
              type: object
              properties:
                cert_file:
                  type: string
                  example: ""
                key_file:
                  type: string
                  example: ""
            min_version:
              type: integer
              example: 0
            ssl_ciphers:
              type: string
              nullable: true
            ssl_certificates:
              type: string
              nullable: true
        security:
          type: object
          properties:
            private_certificate_encoding_secret:
              type: string
              example: ""
            enable_http_secure_endpoints:
              type: boolean
              example: true
            secret:
              type: string
              example: ""
        storage:
          type: object
          properties:
            type:
              type: string
              example: "redis"
            host:
              type: string
              example: "localhost"
            port:
              type: integer
              example: 6379
            master_name:
              type: string
              example: ""
            sentinel_password:
              type: string
              example: ""
            username:
              type: string
              example: ""
            password:
              type: string
              example: ""
            database:
              type: integer
              example: 0
            optimisation_max_idle:
              type: integer
              example: 0
            optimisation_max_active:
              type: integer
              example: 0
            enable_cluster:
              type: boolean
              example: false
            hosts:
              type: string
              nullable: true
            addrs:
              type: string
              nullable: true
            redis_use_ssl:
              type: boolean
              example: false
            redis_ssl_insecure_skip_verify:
              type: boolean
              example: false
            debug:
              type: boolean
              example: false
            timeout:
              type: integer
              example: 0
            use_ssl:
              type: boolean
              example: false
            ssl_insecure_skip_verify:
              type: boolean
              example: false
            ca_file:
              type: string
              example: ""
            cert_file:
              type: string
              example: ""
            key_file:
              type: string
              example: ""
            max_version:
              type: string
              example: ""
            min_version:
              type: string
              example: ""
        analytics:
          type: object
          properties:
            type:
              type: string
              example: "mongo"
            connection_string:
              type: string
              example: ""
            table_sharding:
              type: boolean
              example: false
            batch_size:
              type: integer
              example: 0
            postgres:
              type: object
              properties:
                prefer_simple_protocol:
                  type: boolean
                  example: false
            mysql:
              type: object
              properties:
                default_string_size:
                  type: integer
                  example: 0
                disable_datetime_precision:
                  type: boolean
                  example: false
                dont_support_rename_index:
                  type: boolean
                  example: false
                dont_support_rename_column:
                  type: boolean
                  example: false
                skip_initialize_with_version:
                  type: boolean
                  example: false
            mongo_url:
              type: string
              example: ""
            mongo_use_ssl:
              type: boolean
              example: false
            mongo_ssl_insecure_skip_verify:
              type: boolean
              example: false
            mongo_ssl_allow_invalid_hostnames:
              type: boolean
              example: false
            mongo_ssl_ca_file:
              type: string
              example: ""
            mongo_ssl_pem_keyfile:
              type: string
              example: ""
            mongo_session_consistency:
              type: string
              example: ""
            mongo_batch_size:
              type: integer
              example: 0
            driver:
              type: string
              example: "mongo-go"
            mongo_direct_connection:
              type: boolean
              example: false
        hash_keys:
          type: boolean
          example: true
        session_timeout:
          type: integer
          example: 0
        forward_analytics_to_pump:
          type: boolean
          example: false
        enable_multiple_analytics_keys:
          type: boolean
          example: false
        dont_store_selective:
          type: boolean
          example: false
        dont_store_aggregate:
          type: boolean
          example: false
        org_session_expiration:
          type: integer
          example: 60
        org_session_cleanup:
          type: integer
          example: 60
        license:
          type: string
          example: ""
        aggregates_ignore_tags:
          type: string
          nullable: true
        track_all_paths:
          type: boolean
          example: false
        store_analytics_per_minute:
          type: boolean
          example: false
        ignore_tag_prefix_list:
          type: string
          nullable: true
        threshold_len_tag_list:
          type: integer
          example: 1000
        omit_analytics_index_creation:
          type: boolean
          example: false
        enable_separate_analytics_store:
          type: boolean
          example: false
        analytics_storage:
          type: object
          properties:
            type:
              type: string
              example: ""
            host:
              type: string
              example: ""
            port:
              type: integer
              example: 0
            master_name:
              type: string
              example: ""
            sentinel_password:
              type: string
              example: ""
            username:
              type: string
              example: ""
            password:
              type: string
              example: ""
            database:
              type: integer
              example: 0
            optimisation_max_idle:
              type: integer
              example: 0
            optimisation_max_active:
              type: integer
              example: 0
            enable_cluster:
              type: boolean
              example: false
            hosts:
              type: string
              nullable: true
            addrs:
              type: string
              nullable: true
            redis_use_ssl:
              type: boolean
              example: false
            redis_ssl_insecure_skip_verify:
              type: boolean
              example: false
            debug:
              type: boolean
              example: false
            timeout:
              type: integer
              example: 0
            use_ssl:
              type: boolean
              example: false
            ssl_insecure_skip_verify:
              type: boolean
              example: false
            ca_file:
              type: string
              example: ""
            cert_file:
              type: string
              example: ""
            key_file:
              type: string
              example: ""
            max_version:
              type: string
              example: ""
            min_version:
              type: string
              example: ""
        log_level:
          type: string
          example: "info"
        enable_key_logging:
          type: boolean
          example: false
        sync_worker_config:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
            hash_keys:
              type: boolean
              example: true
            max_batch_size:
              type: integer
              example: 1000
            time_between_batches:
              type: integer
              example: 3
            max_workers:
              type: integer
              example: 1000
            warmup_time:
              type: integer
              example: 0
            group_key_ttl:
              type: integer
              example: 30
        enable_ownership:
          type: boolean
          example: false
    EnvVariable:
      type: object
      properties:
        config_field:
          type: string
          example: "sync_worker_config.warmup_time"
        env:
          type: string
          example: "TYK_MDCB_SYNCWORKERCONFIG_WARMUPTIME"
        value:
          type: string
          example: "0"
        obfuscated:
          type: boolean
          example: false
  securitySchemes:
    api_key:
      in: header
      name: X-Tyk-Authorization
      type: apiKey