OpenADR Alliance MQTT Notifier API

openapi: 3.2.0
info:
  title: Openadr Alliance MQTT Notifier API
  version: 1.0.0
  contact:
    email: info@openadr.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: 'Operations tagged MQTT_notifier across 2 of this provider''s published API definitions: openadr-3-1-0-openapi.yaml, openadr-3-1-1-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
tags:
- name: MQTT_notifier
paths:
  /notifiers/mqtt/topics/programs:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT notifier topic names for operations on programs

        '
      description: 'List all MQTT notifier topic names for operations on programs

        '
      operationId: listAllMqttNotifierTopicsPrograms
      security:
      - oAuth2ClientCredentials:
        - read_all
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/programs/{programID}:
    parameters:
    - name: programID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: objectID of the program object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on a program

        '
      description: 'List all MQTT binding topic names for operations on a program

        '
      operationId: listAllMqttNotifierTopicsProgram
      security:
      - oAuth2ClientCredentials:
        - read_all
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/events:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on all events

        '
      description: 'List all MQTT binding topic names for operations on all events

        '
      operationId: listAllMqttNotifierTopicsEvents
      security:
      - oAuth2ClientCredentials:
        - read_bl
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/programs/{programID}/events:
    parameters:
    - name: programID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: Object ID of the program object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on events for a program

        '
      description: 'List all MQTT binding topic names for operations on events for a program

        '
      operationId: listAllMqttNotifierTopicsProgramEvents
      security:
      - oAuth2ClientCredentials:
        - read_all
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/reports:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on all reports

        '
      description: 'List all MQTT binding topic names for operations on all reports

        '
      operationId: listAllMqttNotifierTopicsReports
      security:
      - oAuth2ClientCredentials:
        - read_bl
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/subscriptions:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on all subscriptions

        '
      description: 'List all MQTT binding topic names for operations on all subscriptions

        '
      operationId: listAllMqttNotifierTopicsSubscriptions
      security:
      - oAuth2ClientCredentials:
        - read_bl
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/vens:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on vens

        '
      description: 'List all MQTT binding topic names for operations on vens

        '
      operationId: listAllMqttNotifierTopicsVens
      security:
      - oAuth2ClientCredentials:
        - read_bl
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/vens/{venID}:
    parameters:
    - name: venID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: venID of the vens object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on a ven

        '
      description: 'List all MQTT binding topic names for operations on a ven

        '
      operationId: listAllMqttNotifierTopicsVen
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/resources:
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on resources

        '
      description: 'List all MQTT binding topic names for operations on resources

        '
      operationId: listAllMqttNotifierTopicsResources
      security:
      - oAuth2ClientCredentials:
        - read_bl
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/vens/{venID}/events:
    parameters:
    - name: venID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: object ID of the ven object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on events targeted for a ven

        '
      description: 'List all MQTT binding topic names for operations on events targated for a ven

        '
      operationId: listAllMqttNotifierTopicsVenEvents
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/vens/{venID}/programs:
    parameters:
    - name: venID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: object ID of the ven object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on programs targeted for a ven

        '
      description: 'List all MQTT binding topic names for operations on programs targeted for a ven

        '
      operationId: listAllMqttNotifierTopicsVenPrograms
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /notifiers/mqtt/topics/vens/{venID}/resources:
    parameters:
    - name: venID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      required: true
      description: object ID of the ven object
    get:
      tags:
      - MQTT_notifier
      summary: 'List all MQTT binding topic names for operations on resources for a ven

        '
      description: 'List all MQTT binding topic names for operations on resources for a ven

        '
      operationId: listAllMqttNotifierTopicsVenResources
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      responses:
        '200':
          $ref: '#/components/responses/notifiersTopicsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
components:
  responses:
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    notifiersTopicsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/notifierTopicsResponse'
    notFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    internalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    badRequest:
      description: The request is malformed or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
  schemas:
    problem:
      type: object
      description: 'reusable error response. From https://opensource.zalando.com/problem/schema.yaml.

        '
      properties:
        type:
          type: string
          format: uri
          minLength: 2
          maxLength: 8000
          description: 'An absolute URI that identifies the problem type.

            When dereferenced, it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://zalando.github.io/problem/constraint-violation
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable.

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          minLength: 3
          maxLength: 8000
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
    notifierTopicsResponse:
      type: object
      required:
      - topics
      properties:
        topics:
          $ref: '#/components/schemas/notifierOperationsTopics'
    objectID:
      type: string
      pattern: ^[a-zA-Z0-9_-]*$
      minLength: 1
      maxLength: 128
      description: URL safe VTN assigned object ID.
      example: object-999
    notifierOperationsTopics:
      type: object
      description: MQTT notifier topic names for notifications of subscribable-object operations
      required:
      - UPDATE
      - DELETE
      properties:
        CREATE:
          type: string
          description: "'Topic path for CREATE operations,\n not provided for notifications for a specific object ID,\n e.g. until programID foo is created, clients unable to\n request notifications of its creation'\n"
          example: '{objectType}s/create'
        UPDATE:
          type: string
          description: Topic path for UPDATE operations
          example: '{objectType}s/update'
        DELETE:
          type: string
          description: Topic path for DELETE operations
          example: '{objectType}s/delete'
        ALL:
          type: string
          description: Topic path for ALL operations, if supported by VTN
          example: '{objectType}s/+'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: Client credential flow.
      flows:
        clientCredentials:
          tokenUrl: auth/token
          scopes:
            read_all: BL can read all resources
            read_targets: VENs may only read objects with targets by providing matching targets
            read_ven_objects: VENs may only read objects whose clientID matches their own
            write_programs: Only BL can write to programs
            write_events: Only BL can write to events
            write_reports: only VENs can write to reports
            write_subscriptions: VENs and BL can write to subscriptions
            write_vens: VENS and BL can write to vens and resources
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- openadr-3-1-0-openapi.yaml
- openadr-3-1-1-openapi.yaml