OpenADR Alliance Resources API

openapi: 3.2.0
info:
  title: Openadr Alliance Resources 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 resources 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: resources
paths:
  /resources:
    get:
      tags:
      - resources
      summary: search ven resources
      operationId: searchVenResources
      description: 'List all ven resources associated with ven with specified venID.

        May filter results by resourceName as query params.

        May filter results by targets params.

        Use skip and pagination query params to limit response size.

        '
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      parameters:
      - name: resourceName
        in: query
        description: Indicates resource objects with resourceName
        required: false
        schema:
          $ref: '#/components/schemas/resourceName'
      - name: venID
        in: query
        description: Indicates resource objects with venID
        required: false
        schema:
          $ref: '#/components/schemas/objectID'
      - name: targets
        in: query
        description: Indicates targets
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/target'
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        style: form
        explode: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 0
          type: integer
          format: int32
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/resource'
        '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'
    post:
      tags:
      - resources
      summary: create resource
      operationId: createResource
      description: Create a new resource.
      security:
      - oAuth2ClientCredentials:
        - write_vens
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resourceRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
  /resources/{resourceID}:
    parameters:
    - name: resourceID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      description: object ID of the resource.
      required: true
    get:
      tags:
      - resources
      summary: search ven resources by ID
      operationId: searchVenResourceByID
      description: Return the ven resource specified by venID and resourceID specified in path.
      security:
      - oAuth2ClientCredentials:
        - read_ven_objects
      - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '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'
    put:
      tags:
      - resources
      summary: update  ven resource
      operationId: updateVenResource
      description: Update the ven resource specified by venID and resourceID specified in path.
      security:
      - oAuth2ClientCredentials:
        - write_vens
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resourceRequest'
        description: resource item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
    delete:
      tags:
      - resources
      summary: delete  ven resource
      operationId: deleteVenResource
      description: Delete the ven resource specified by venID and resourceID specified in path.
      security:
      - oAuth2ClientCredentials:
        - write_vens
      - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '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:
  schemas:
    valuesMap:
      type: object
      description: 'Represents one or more values associated with a type.


        See enumerations in Definitions for defined string values, or use privately defined strings

        '
      required:
      - type
      - values
      properties:
        type:
          type: string
          minLength: 1
          maxLength: 128
          description: 'Represents the nature of values.


            See enumerations in Definitions for defined string values, or use privately defined strings

            '
          example: PRICE
        values:
          type: array
          description: A list of data points. Most often a singular value such as a price.
          example:
          - 0.17
          items:
            anyOf:
            - type: number
            - type: integer
            - type: string
            - type: boolean
            - $ref: '#/components/schemas/point'
    resource:
      type: object
      description: Server provided representation of resource
      allOf:
      - $ref: '#/components/schemas/objectMetadata'
      - $ref: '#/components/schemas/BlResourceRequest'
    target:
      type: string
      minLength: 1
      maxLength: 128
      description: User generated target string.
      example: group-1
    objectTypes:
      type: string
      description: Types of objects addressable through API.
      example: EVENT
      enum:
      - PROGRAM
      - EVENT
      - REPORT
      - SUBSCRIPTION
      - VEN
      - RESOURCE
    objectMetadata:
      type: object
      description: metadata common to all addressable objects. Values provided by VTN on object creation.
      required:
      - id
      - createdDateTime
      - modificationDateTime
      - objectType
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          $ref: '#/components/schemas/objectTypes'
    resourceName:
      type: string
      minLength: 1
      maxLength: 128
      description: User generated identifier. A value of AGGREGATED_REPORT indicates an aggregation of more that one resource's data
      example: RESOURCE-999
    point:
      type: object
      description: A pair of floats typically used as a point on a 2 dimensional grid.
      required:
      - x
      - y
      properties:
        x:
          type: number
          format: float
          description: A value on an x axis.
          example: 1.0
        y:
          type: number
          format: float
          description: A value on a y axis.
          example: 2.0
    dateTime:
      type: string
      format: date-time
      description: datetime in RFC 3339 format
      example: 2023-06-15 09:30:00+00:00
    VenResourceRequest:
      type: object
      description: 'Business Logic provided representation of ven resource.

        '
      required:
      - objectType
      - resourceName
      - venID
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum:
          - VEN_RESOURCE_REQUEST
        resourceName:
          $ref: '#/components/schemas/resourceName'
        venID:
          $ref: '#/components/schemas/objectID'
        attributes:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          default: null
    BlResourceRequest:
      type: object
      description: 'Business Logic provided representation of ven resource.

        '
      required:
      - objectType
      - clientID
      - resourceName
      - venID
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum:
          - BL_RESOURCE_REQUEST
        clientID:
          $ref: '#/components/schemas/clientID'
        targets:
          type:
          - array
          - 'null'
          description: A list of targets.
          items:
            $ref: '#/components/schemas/target'
          default: null
        resourceName:
          $ref: '#/components/schemas/resourceName'
        venID:
          $ref: '#/components/schemas/objectID'
        attributes:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          default: null
    objectID:
      type: string
      pattern: ^[a-zA-Z0-9_-]*$
      minLength: 1
      maxLength: 128
      description: URL safe VTN assigned object ID.
      example: object-999
    clientID:
      type: string
      description: 'ClientID as provisioned by Auhtentication Service and associated with client''s bearer token

        '
      minLength: 1
      maxLength: 128
      example: 249rj49jiej
    resourceRequest:
      oneOf:
      - $ref: '#/components/schemas/BlResourceRequest'
      - $ref: '#/components/schemas/VenResourceRequest'
    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.

            '
    resourceName_2:
      type: string
      minLength: 1
      maxLength: 128
      description: 'User generated identifier.

        A value of AGGREGATED_REPORT indicates an aggregation of more that one resource''s data

        '
      example: RESOURCE-999
    VenResourceRequest_2:
      type: object
      description: 'Business Logic provided representation of ven resource.

        '
      required:
      - objectType
      - resourceName
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum:
          - VEN_RESOURCE_REQUEST
        resourceName:
          $ref: '#/components/schemas/resourceName_2'
        attributes:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          default: null
    BlResourceRequest_2:
      type: object
      description: 'Business Logic provided representation of ven resource.

        '
      required:
      - objectType
      - resourceName
      - venID
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum:
          - BL_RESOURCE_REQUEST
        targets:
          type:
          - array
          - 'null'
          description: A list of targets.
          items:
            $ref: '#/components/schemas/target'
        resourceName:
          $ref: '#/components/schemas/resourceName_2'
        venID:
          $ref: '#/components/schemas/objectID'
        attributes:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          default: null
  responses:
    internalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    conflict:
      description: Conflict. Could for example be a violation of a foreign key constraint or of a unique constraint on a name or id.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    notFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    badRequest:
      description: The request is malformed or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
    conflict_2:
      description: 'Conflict. Could for example be a violation of a foreign key constraint

        or of a unique constraint on a name or id.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
  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