core-command.yaml

openapi: 3.0.0
info:
  title: Edgex Foundry - Core Command API
  description: This is the definition of the API for the Core Command service in the EdgeX Foundry IOT microservice platform. Core Command is responsible for storing command definitions and also for executing those commands as reads and writes against target devices.
  version: 2.x
  
servers:
  - url: http://localhost:48082/api/v2
    description: URL for local development and testing
  
components:
  schemas:
    ActionResponse:
      type: object
      properties:
        code:
          type: string
        description:
          type: string
        expectedValues:
          type: array
          items:
            type: string
    Command:
      type: object
      properties:
        created:
          type: integer
        get:
          $ref: '#/components/schemas/CommandAction'
        id:
          type: string
          format: uuid
        modified:
          type: integer
        name:
          type: string
        put:
          $ref: '#/components/schemas/CommandAction'
    CommandAction:
      type: object
      properties:
        path:
          type: string
        responses:
          type: array
          items:
            $ref: '#/components/schemas/ActionResponse'
        url:
          type: string
    CommandResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "For the specified device, provides a list of the associated commands."
      type: object
      properties:
        device:
          description: "Indicates a device. Will be either the device ID or name depending on how the request was made."
          type: string
        commands:
          type: array
          items:
            $ref: '#/components/schemas/Command'
    CorrelatedRequest:
      description: "Provides a correlation ID that can be used when grouping multiple requests into a single batch. For example, multiple commands can be issued at once. Each IssueCommandRequest has its own request identifier while the batch has an overall identifier. This allows for visibility into whether or not a response was obtained for every request in the batch."
      type: object
      properties:
        correlationId:
          description: "Identifies the batch to which this request belongs. If used via REST, this value should be the same as that of  the ''X-Correlation-ID'' HTTP header."
          type: string
          format: uuid
          example: "82eb2e26-0f24-48aa-ae4c-de9dac3fb9bc"
        requestId:
          description: "Uniquely identifies this request apart from its peers in the batch. For implementation, recommend this value be generated by the type's constructor."
          type: string
          format: uuid
          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
      required:
        - correlationId
        - requestId
    CorrelatedResponse:
      description: "Provides a correlation ID that can be used when grouping multiple responses into a single batch. For example, multiple commands can be issued at once. The responses can be returned as a batch or individually. It doesn't matter as long as both of these properties are correctly set because either way the caller will have visibility into whether or not a response was obtained for every request in the batch."
      type: object
      properties:
        correlationId:
          description: "Identifies the batch to which this response belongs. If used via REST, this value should be the same as that of  the ''X-Correlation-ID'' HTTP header."
          type: string
          format: uuid
          example: "82eb2e26-0f24-48aa-ae4c-de9dac3fb9bc"
        requestId:
          description: "Uniquely identifies the request within the larger batch resulting in this response."
          type: string
          format: uuid
          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
        statusCode:
          description: "A numeric code signifying the operational status of the response."
          type: integer
        message:
          description: "A field that can contain a free-form message, such as an error message."
          type: string
      required:
        - correlationId
        - requestId
    IssueCommandRequest:
      allOf:
        - $ref: '#/components/schemas/CorrelatedRequest'
      description: "A request type specifying an individual command for execution."
      type: object
      properties:
        deviceId:
          type: string
          format: uuid
          description: "Refers to the device targeted by the command. Could be either the device ID or name."
        commandId:
          type: string
          format: uuid
          description: "Refers to the command being invoked. Could be either the command ID or name."
      required:
      - device
      - command
    IssueCommandResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "Provides a response with details about whether invocation of a given command was successful."
      type: object
      properties:
        device:
          type: string
          description: "Refers to the device targeted by the command. Could be either the device ID or name."
        command:
          type: string
          description: "Refers to the command being invoked. Could be either the command ID or name."
      required:
      - device
      - command
    PingResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        timestamp:
          type: string
          description: "Outputs the current server timestamp in RFC1123 format"
          example: "Mon, 02 Jan 2006 15:04:05 MST"
    RequestEnvelope:
      description: "A wrapper type for use when sending a request to the /batch endpoint. Each individual request type in the HTTP request should be wrapped in an envelope to facilitate instantiation of the correct routing handler. See property descriptions below for more details."
      type: object
      properties:
        action:
          type: string
          description: "Indicates the type of operation applicable to the wrapped request. Valid values are 'create','read','update','delete', and 'command'"
        content:
          type: string
          format: byte
          description: "A byte array containing a marshalled request type instance. This is the specific, semantically identifiable request -- such as an AddDeviceRequest."
        strategy:
          type: string
          description: "Indicates the expectation of whether a response should be produced synchronously or asynchronously. If asynchronously, desire for either a polling or push/callback should be provided. Valid values are 'sync','async-push','async-poll'"
        type:
          type: string
          description: "The name of the type applicable to the request instance contained in the 'content' property."
        version:
          description: "Proposed field for explicitly defining version of request DTO. This is for advertising compatibility between a publisher/subscriber or requester/receiver"
          type: string
          example: "2.0.x"
      required:
        - action
        - content
        - strategy
        - type
        - version
    ResponseEnvelope:
      description: "A wrapper type for use when receiving a response from the /batch endpoint. Each individual response type in the HTTP response should be wrapped in an envelope to facilitate unmarshalling by the client. See property descriptions below for more details."
      type: object
      properties:
        action:
          type: string
          description: "Indicates the type of operation applicable to the wrapped response. This should be recapitulated from the originating request. Valid values are 'create','read','update','delete', and 'command'"
        content:
          type: string
          format: byte
          description: "A byte array containing a marshalled response type instance. This is the specific, semantically identifiable response -- such as an AddDeviceResponse."
        strategy:
          type: string
          description: "Recapitulates the expectation with regard to the delivery of response that was specified on the originating request. Valid values are 'sync','async-push','async-poll'"
        type:
          type: string
          description: "The name of the type applicable to the response instance contained in the 'content' property."
        version:
          description: "Proposed field for explicitly defining version of response DTO. This is for advertising compatibility between a publisher/subscriber or requester/receiver"
          type: string
          example: "2.0.x"
      required:
        - action
        - content
        - strategy
        - type
        - version
  parameters:
    offsetParam:
      in: query
      name: offset
      required: false
      schema:
        type: integer
        minimum: 0
      description: "The number of items to skip before starting to collect the result set."
    limitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
      description: "The numbers of items to return."
    correlatedRequestHeader:
      in: header
      name: X-Correlation-ID
      description: "A unique identifier correlating a request to its associated response, facilitating tracing through being included on requests originating from the initiating request."
      schema:
        type: string
        format: uuid
      required: true
      example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
  headers:
    correlatedResponseHeader:
      description: "A response header that returns the unique correlation ID used to initiate the request."
      schema:
        type: string
        format: uuid
      required: true
      example: "14a42ea6-c394-41c3-8bcd-a29b9f5e6835"
paths:
  /batch:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: "Accepts an arbitrary number of RequestEnvelope instances. Each RequestEnvelope has a 'content' property that holds a specific request type. This endpoint is operation agnostic will route the request to the appropriate handler implementation within the service."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RequestEnvelope'
      responses:
        '207':
          description: "Indicates a multi-part response supportive of accepting multiple requests at once. The 'statusCode' property of each response in the returned array will indicate success or failure."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseEnvelope'
  /command:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    put:
      summary: "Allows for the issuance of multiple commands in a batch. Commands will be executed as either read or write according to their definition."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/IssueCommandRequest'
      responses:
        '207':
          description: "Indicates a multi-part response supportive of accepting multiple requests at once. The 'statusCode' property of each response in the returned array will indicate success or failure."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IssueCommandResponse'
  /device/id/{deviceid}/command/{commandid}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: deviceid
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: "An ID of datatype string, by default a GUID. Uniquely identifies a device."
      - name: commandid
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: "An ID of datatype string, by default a GUID. Uniquely identifies a command."
    get:
      summary: "Issue the specified read command referenced by the command id to the device/sensor, also referenced by id."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '423':
          description: "The device is locked (AdminState)"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
    put:
      summary: "Issue the specified write command referenced by the command id to the device/sensor, also referenced by id."
      responses:
        '207':
          description: "Indicates a multi-part response supportive of accepting multiple requests at once. The 'statusCode' property of each response in the returned array will indicate success or failure."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IssueCommandResponse'
  /device/name/{deviceName}/command/{commandName}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: deviceName
        in: path
        required: true
        schema:
          type: string
        description: "A name uniquely identifying a device."
      - name: commandName
        in: path
        required: true
        schema:
          type: string
        description: "A name uniquely identifying a command."
    get:
      summary: "Issue the specified read command referenced by the command name to the device/sensor, also referenced by name."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '423':
          description: "The device is locked (AdminState)"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCommandResponse'
    put:
      summary: "Issue the specified write command referenced by the command name to the device/sensor, also referenced by name."
      responses:
        '207':
          description: "Indicates a multi-part response supportive of accepting multiple requests at once. The 'statusCode' property of each response in the returned array will indicate success or failure."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IssueCommandResponse'
  /device/id/{id}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: "An ID of datatype string, by default a GUID. Uniquely identifies a device."
    get:
      summary: "Returns all commands associated with the specified device."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
  /device/name/{name}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: "The unique name of a device."
    get:
      summary: "Returns all commands associated with the specified device."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
  /device/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Returns a paginated list of CommandResponses. The list contains all of the commands in the system associated with their respective device."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CommandResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CommandResponse'
  /ping:
    get:
      summary: "A simple 'ping' endpoint that can be used as a service healthcheck"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'