openapi: 3.2.0
info:
  title: Weidmueller Consumer API
  version: 1.3.0
  contact:
    name: Weidmüller Interface GmbH & Co. KG
    url: https://www.weidmueller.com/
    email: oss@weidmueller.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT.html
  description: 'Operations tagged Consumer across 2 of this provider''s published API definitions: variable-http-openapi.yaml, weidmueller-variable-http-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /u-os-hub/api/v1
  description: A synchronous HTTP API for accessing variables.
tags:
- name: Consumer
  description: 'A consumer may


    - list/get available providers

    - list/get/update variables published by providers.'
paths:
  /providers:
    get:
      tags:
      - Consumer
      summary: List providers
      description: List providers.
      operationId: get_providers_handler
      responses:
        '200':
          description: A list of providers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseSingleProvider'
              example:
              - id: u_os_adm
              - id: u_os_sbm
        default:
          description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 422 or 500. See body for a detailed error message.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
      security:
      - OAuth2:
        - hub.variables.readonly
      - OAuth2:
        - hub.variables.readwrite
    servers:
    - url: /u-os-hub/api/v1
      description: A synchronous HTTP API for accessing variables.
  /providers/{provider_id}/variables:
    get:
      tags:
      - Consumer
      summary: List variable values of a single provider
      description: 'List all variable values or a subset of variable values of a single provider with or without variable definitions.

        Variables that contain values which are incompatible with the currently used u-OS data hub API version are filtered out.'
      operationId: get_variables_handler
      parameters:
      - name: provider_id
        in: path
        description: Id of a provider
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
      - name: prefixes
        in: query
        description: "This parameter is used to filter variables by prefixes. The parameter shall contain a comma-separated list of prefixes. The response will include all variables where the variable key matches one of the given prefixes.\n            The endpoint will filter out duplicates: Each variable will occur only once in the response array."
        required: false
        schema:
          $ref: '#/components/schemas/Prefixes'
      - name: definition
        in: query
        description: If true, the response will contain variable definitions.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Variables of a single provider with or without variable definitions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseSingleRead'
              examples:
                VariablesWithDefinition:
                  value:
                  - definition:
                      access_type: READ_ONLY
                      data_type: STRING
                      experimental: false
                    key: digital_nameplate.software_version
                    value: 2.2.0
                  - definition:
                      access_type: READ_ONLY
                      data_type: STRING
                      experimental: false
                    key: digital_nameplate.hardware_version
                    value: 1.23.0
                VariablesWithoutDefinition:
                  value:
                  - key: digital_nameplate.software_version
                    value: 2.2.0
                  - key: digital_nameplate.hardware_version
                    value: 1.23.0
        default:
          description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 422 or 500. See body for a detailed error message.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
      security:
      - OAuth2:
        - hub.variables.readonly
      - OAuth2:
        - hub.variables.readwrite
    post:
      tags:
      - Consumer
      summary: Update variable values of a single provider
      description: Update all variable values or a subset of variable values of a single provider.
      operationId: post_multiple_variables_handler
      parameters:
      - name: provider_id
        in: path
        description: Id of a provider
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
      requestBody:
        description: The request body contains the variable values which shall be updated.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/VariableUpdatePostPayload'
            example:
            - key: ur20_4do_p_1.process_data.channel_0.do
              value: true
            - key: ur20_4do_p_1.process_data.channel_1.do
              value: false
        required: true
      responses:
        '200':
          description: "Ok\n\n            Variable write command was successfully sent.\n            The updated variables are not being returned because the provider may query the write and apply the changes asynchronously. The value write might occur later or could be overridden by another write, thus never being applied."
        '400':
          description: Wrong data type written for variable.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
        '405':
          description: Tried to write a readonly variable.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
        default:
          description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 422 or 500. See body for a detailed error message.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
      security:
      - OAuth2:
        - hub.variables.readwrite
    servers:
    - url: /u-os-hub/api/v1
      description: A synchronous HTTP API for accessing variables.
  /providers/{provider_id}/variables/{variable_key}:
    get:
      tags:
      - Consumer
      summary: Get variable value of a single provider
      description: Get variable value of a single provider with or without variable definition.
      operationId: get_single_variable_handler
      parameters:
      - name: provider_id
        in: path
        description: Id of a provider
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
      - name: variable_key
        in: path
        description: Key of a variable
        required: true
        schema:
          $ref: '#/components/schemas/VariableName'
      - name: definition
        in: query
        description: If true, the response will contain variable definitions.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A variable value with or without definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseSingleRead'
              examples:
                VariableWithDefinition:
                  value:
                    definition:
                      access_type: READ_ONLY
                      data_type: STRING
                      experimental: false
                    key: digital_nameplate.software_version
                    value: 2.2.0
                VariableWithoutDefinition:
                  value:
                    key: digital_nameplate.software_version
                    value: 2.2.0
        default:
          description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 422 or 500. See body for a detailed error message.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
      security:
      - OAuth2:
        - hub.variables.readonly
      - OAuth2:
        - hub.variables.readwrite
    post:
      tags:
      - Consumer
      summary: Update variable value of a single provider
      description: Update variable value of a single provider.
      operationId: post_single_variable_handler
      parameters:
      - name: provider_id
        in: path
        description: Name of a Provider
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
      - name: variable_key
        in: path
        description: Key of a variable
        required: true
        schema:
          $ref: '#/components/schemas/VariableName'
      requestBody:
        description: The request body contains the variable value which shall be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariableUpdatePostPayload'
            example:
              key: ur20_4do_p_1.process_data.channel_1.do
              value: true
        required: true
      responses:
        '200':
          description: ''
        '400':
          description: Wrong data type written for variable, or variable key does not match request.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
        '405':
          description: Tried to write a readonly variable.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
        default:
          description: Common HTTP Error codes may be thrown by this method, such as 400, 401, 403, 404, 422 or 500. See body for a detailed error message.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FormatlessString'
      security:
      - OAuth2:
        - hub.variables.readwrite
    servers:
    - url: /u-os-hub/api/v1
      description: A synchronous HTTP API for accessing variables.
components:
  schemas:
    VariableDefinition:
      type: object
      required:
      - data_type
      - access_type
      properties:
        access_type:
          $ref: '#/components/schemas/VariableAccessType'
        data_type:
          $ref: '#/components/schemas/VariableDataType'
        experimental:
          type: boolean
    ISO8601Duration:
      type: string
      format: ^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$
      description: 'A duration string according to ISO8601 norm (https://datatracker.ietf.org/doc/html/rfc3339#appendix-A).


        Example: ''PT5H9M39.400S'''
      maxLength: 82
    VariableAccessType:
      type: string
      enum:
      - READ_ONLY
      - READ_WRITE
    Prefixes:
      type: string
      format: ^[a-zA-Z_]([a-zA-Z0-9_]{0,62})?(\.[a-zA-Z_]([a-zA-Z0-9_]{0,62})?)*$
      description: A comma-separated list of prefixes used for listing a subset of variables.
      maxLength: 1023
    ResponseSingleProvider:
      type: object
      description: Response containing a single provider.
      required:
      - id
      properties:
        id:
          type: string
          format: ^[a-z]([a-z0-9_]{0,61}[a-z0-9])?$
          maxLength: 63
    ProviderName:
      type: string
      format: ^[a-z]([a-z0-9_]{0,61}[a-z0-9])?$
      description: The id of a provider.
      maxLength: 63
    ResponseSingleRead:
      type: object
      description: Response object for a single variable.
      required:
      - key
      - value
      - quality
      - timestamp
      properties:
        definition:
          $ref: '#/components/schemas/VariableDefinition'
        key:
          type: string
          format: ^[a-zA-Z_]([a-zA-Z0-9_]{0,62})?(\.[a-zA-Z_]([a-zA-Z0-9_]{0,62})?)*$
          maxLength: 1023
        quality:
          $ref: '#/components/schemas/VariableQuality'
        timestamp:
          $ref: '#/components/schemas/ISO8601Timestamp'
        value:
          $ref: '#/components/schemas/VariableValue'
    VariableValue:
      oneOf:
      - type: integer
        format: int64
      - type: boolean
      - $ref: '#/components/schemas/FormatlessString'
      - type: number
        format: double
      - $ref: '#/components/schemas/ISO8601Duration'
      - $ref: '#/components/schemas/ISO8601Timestamp'
    ISO8601Timestamp:
      type: string
      format: date-time
      description: 'A timestamp string according to ISO8601 norm (https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).


        Example: ''1970-01-01T00:20:34.000Z'''
      maxLength: 24
    FormatlessString:
      type: string
      format: string
      description: String without special format.
      maxLength: 1023
    VariableDataType:
      type: string
      enum:
      - BOOLEAN
      - DURATION
      - FLOAT64
      - INT64
      - STRING
      - TIMESTAMP
    VariableName:
      type: string
      format: ^[a-zA-Z_]([a-zA-Z0-9_]{0,62})?(\.[a-zA-Z_]([a-zA-Z0-9_]{0,62})?)*$
      description: String that contains the key of a variable.
      maxLength: 1023
    VariableUpdatePostPayload:
      type: object
      description: The JSON payload of a POST request (to update a single variable) is deserialized into this struct.
      required:
      - key
      - value
      properties:
        key:
          type: string
          format: ^[a-zA-Z_]([a-zA-Z0-9_]{0,62})?(\.[a-zA-Z_]([a-zA-Z0-9_]{0,62})?)*$
          maxLength: 1023
        value:
          $ref: '#/components/schemas/VariableValue'
    VariableQuality:
      type: string
      enum:
      - BAD
      - GOOD
      - UNCERTAIN
      - UNCERTAIN_LAST_USABLE_VALUE
      - UNCERTAIN_INITIAL_VALUE
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            hub.variables.readonly: Read-only access to Data Hub variables.
            hub.variables.readwrite: Read and write access to Data Hub variables.
      description: The HTTP API uses the OAuth2 client credentials flow.
x-refined-from:
- variable-http-openapi.yaml
- weidmueller-variable-http-openapi.yml