core-data.yaml

openapi: 3.0.0
info:
  title: Edgex Foundry - Core Data API
  description: This is the definition of the API for the Core Data service in the EdgeX Foundry IOT microservice platform. Core Data is responsible for storing event and reading data ingested from edge devices in the environment.
  version: 2.x
  
servers:
  - url: http://localhost:48080/api/v2
    description: URL for local development and testing
  
components:
  schemas:
    AddEventRequest:
      allOf:
        - $ref: '#/components/schemas/CorrelatedRequest'
      description: "A request for ingesting a new event/reading data"
      type: object
      properties:
        device:
          description: "The name of the device from which the event originated"
          type: string
        origin:
          description: "A Unix timestamp indicating when the event was originated at the source device (can support nanoseconds)"
          type: integer
        readings:
          description: "One or more readings captured at the time of the event"
          type: array
          items:
            $ref: '#/components/schemas/BaseReading'
      required:
        - device
        - origin
        - readings
    AddEventResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "A response type for use in adding a new Event. The ID of the new record will be returned to the caller. An optional message property allows for miscellaneous information to be returned."
      type: object
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
      required:
        - id
    BaseReading:
      description: "A base reading type containing common properties from which more specific reading types inherit. This definition should not be implemented but is used elsewhere to indicate support for a mixed list of simple/binary readings in a single event."
      type: object
      properties:
        created:
          description: "A Unix timestamp indicating when (if) the reading was initially persisted to a database."
          type: integer
        device:
          description: "The name of the device from which the reading originated"
          type: string
        id:
          description: "The unique identifier for the reading"
          type: string
          format: uuid
        labels:
          description: "One or more custom labels that can be assigned to a reading"
          type: array
          items:
            type: string
        modified:
          description: "A Unix timestamp indicating the most recent modification of the reading data in a persistent database."
          type: integer
        origin:
          description: "A Unix timestamp indicating when the reading was originated at the source device (can support nanoseconds)"
          type: integer
        pushed:
          description: "A Unix timestamp indicating when the reading was permanently pushed to a northside app/service"
          type: integer
    BinaryReading:
      description: "An event reading for a binary data type"
      allOf:
        - $ref: '#/components/schemas/BaseReading'
        - type: object
          properties:
            binaryValue:
              description: "If the value of the reading is binary, it will be found in this property as a byte array"
              type: string
              format: byte
            mediaType:
              description: "E.g. MIME Type, indicates what the content type of the binaryValue property is if it's populated."
              type: string
    CorrelatedRequest:
      description: "Provides a correlation ID that can be used when grouping multiple requests into a single batch. For example, multiple events can be posted at once. Each AddEventRequest 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 events can be posted 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
    EventCountResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "Returns an aggregate event count. If the deviceId property is blank then the count is applicable to all events in the database. Otherwise, the count is applicable to the specified device."
      type: object
      properties:
        count:
          type: integer
        deviceId:
          type: string
          format: uuid
      required:
        - count
    Event:
      description: "A discrete event containing one or more readings"
      properties:
        created:
          description: "A Unix timestamp indicating when (if) the event was initially persisted to a database."
          type: integer
        device:
          description: "The name of the device from which the event originated"
          type: string
        id:
          description: "The unique identifier for the event"
          type: string
          format: uuid
        modified:
          description: "A Unix timestamp indicating the most recent modification of the event data in a persistent database."
          type: integer
        origin:
          description: "A Unix timestamp indicating when the event was originated at the source device (can support nanoseconds)"
          type: integer
        pushed:
          description: "A Unix timestamp indicating when the event was permanently pushed to a northside app/service"
          type: integer
        readings:
          description: "One or more readings captured at the time of the event"
          type: array
          items:
            $ref: '#/components/schemas/BaseReading'
    EventResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "A response type for returning an Event to the caller."
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
    PingResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        timestamp:
          description: "Outputs the current server timestamp in RFC1123 format"
          example: "Mon, 02 Jan 2006 15:04:05 MST"
          type: string
    ReadingCountResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      description: "Returns an aggregate reading count. If the deviceId property is blank then the count is applicable to all readings in the database. Otherwise, the count is applicable to the specified device."
      type: object
      properties:
        count:
          type: integer
        deviceId:
          type: string
          format: uuid
      required:
        - count
    ReadingResponse:
      allOf:
        - $ref: '#/components/schemas/ReadingResponse'
      description: "A response type for returning a Reading to the caller. The Reading may be of either type BinaryReading or type SimpleReading."
      type: object
      properties:
        reading:
          $ref: '#/components/schemas/BaseReading'
    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
    SimpleReading:
      description: "An event reading for a simple data type"
      allOf:
        - $ref: '#/components/schemas/BaseReading'
        - type: object
          properties:
            floatEncoding:
              description: "Indicates how a float value is encoded, if the value property contains a float."
              type: string
            type:
              description: "Indicates the datatype of the value property"
              type: string
            value:
              description: "A string representation of the reading's value"
              type: string
    SimpleReadingResponse:
      allOf:
        - $ref: '#/components/schemas/ReadingResponse'
      description: "A response type for returning a Reading to the caller. The Reading may only be of type SimpleReading."
      type: object
      properties:
        reading:
          $ref: '#/components/schemas/SimpleReading'
    UpdateEventPushedByChecksumRequest:
      description: "A request to facilitate updating the 'pushed' timestamp on an event according to its checksum."
      allOf:
        - $ref: '#/components/schemas/CorrelatedRequest'
        - type: object
          properties:
            checksum:
              type: string
      required:
      - checksum
    UpdateEventPushedByChecksumResponse:
      description: "A response indicating success/failure to update the 'pushed' timestamp on an event according to its checksum."
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        checksum:
          type: string
      required:
      - checksum
    ValueDescriptor:
      description: "Defines constraints for ingested data via SimpleReadings"
      properties:
        created:
          description: "A Unix timestamp indicating when (if) the value descriptor was initially persisted to a database."
          type: integer
        defaultValue:
          description: "A default value for a value descriptor supporting a simple datatype"
          type: object
        description:
          description: "A simple description supporting the value descriptor"
          type: string
        formatting:
          description: "A format string, if required, for the reading value"
          type: string
        id:
          description: "The unique identifier for the value descriptor"
          type: string
          format: uuid
        labels:
          description: "One or more custom labels that can be assigned to a value descriptor's reading"
          type: array
          items:
            type: string
        max:
          description: "A maximum supported value for a numeric value descriptor"
          type: object
        min:
          description: "A minimum supported value for a numeric value descriptor"
          type: object
        modified:
          description: "A Unix timestamp indicating the most recent modification of the event data in a persistent database."
          type: integer
        name:
          description: "A unique name identifying the value descriptor"
          type: string
        type:
          description: "Indicates the datatype of readings associated with the value descriptor"
          type: string
        uomLabel:
          description: "A custom unit-of-measure label"
          type: string
  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/ResponseEnvelope'
      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'
  /event:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: "Allows for the ingestion of event/reading data"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddEventRequest'
      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/AddEventResponse'
  /event/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Given the entire range of events sorted by last modified descending, returns a portion of that range according to the offset and limit parameters."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '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/EventResponse'
  /event/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."
    get:
      summary: "Returns an event by ID"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
    delete:
      summary: "Deletes an event by ID"
      responses:
        '204':
          description: "Delete successful"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
  /event/pushed:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    put:
      summary: "For an event with the supplied checksum value, update the pushed time indicating successful propogation to northside apps/services."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateEventPushedByChecksumRequest'
      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/UpdateEventPushedByChecksumResponse'
  /event/count:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    get:
      summary: "Return a count of all of events currently stored in the database."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
  /event/count/device/{deviceId}:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: deviceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: "Uniquely identifies a given device"
    get:
      summary: "Return a count of all of events currently stored in the database, sourced from the specified device."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCountResponse'
  /event/device/{deviceId}:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: deviceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: "Uniquely identifies a given device"
    delete:
      summary: "Deletes all events for the specified device"
      responses:
        '204':
          description: "Delete successful"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/EventResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/EventResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/EventResponse'
  /event/device/{deviceId}/all:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: deviceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: "Uniquely identifies a given device"
    - $ref: '#/components/parameters/offsetParam'
    - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Given a range of events from the specified device sorted by last modified descending, returns a portion of that range according to the offset and limit parameters."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '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/EventResponse'
  /event/start/{start}/end/{end}:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: start
      in: path
      required: true
      schema:
        type: integer
      description: "Unix timestamp indicating the start of a date/time range"
    - name: end
      in: path
      required: true
      schema:
        type: integer
      description: "Unix timestamp indicating the end of a date/time range"
    - $ref: '#/components/parameters/offsetParam'
    - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Return a paginated range of events with a create date inside the specified start/end values."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/EventResponse'
        '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/EventResponse'
  /event/age/{age}:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: age
      in: path
      required: true
      schema:
        type: integer
      description: "Age in milliseconds since created timestamp for a given event"
    delete:
      summary: "Remove all old events (and associated readings) based on delimiting age"
      responses:
        '204':
          description: "Delete successful"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
  /event/scrub:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    delete:
      summary: "Remove all pushed events and their associated readings."
      responses:
        '204':
          description: "Delete successful"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
  /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'
  /reading/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - in: query
        name: labels
        required: false
        schema:
          type: string
        description: "Allows for querying readings by associated user-defined label. More than one label may be specified via a comma-delimited list."
    get:
      summary: "Given the entire range of readings sorted by last modified descending, returns a portion of that range according to the offset and limit parameters. Readings returned will all inherit from BaseReading but their concrete types will be either SimpleReading or BinaryReading, potentially interleaved. Readings may be filtered by label."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/ReadingResponse'
        '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/ReadingResponse'
  /reading/count:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    get:
      summary: "Return a count of all of readings currently stored in the database."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadingCountResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadingCountResponse'
  /reading/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."
    get:
      summary: "Returns a reading by ID"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadingResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadingResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadingResponse'
  /reading/device/{deviceId}/all:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: deviceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: "Uniquely identifies a given device"
    - $ref: '#/components/parameters/offsetParam'
    - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Given a range of readings from the specified device sorted by last modified descending, returns a portion of that range according to the offset and limit parameters."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/ReadingResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadingResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadingResponse'
        '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/ReadingResponse'
  /reading/type/{type}:
    parameters:
    - $ref: '#/components/parameters/correlatedRequestHeader'
    - name: type
      in: path
      required: true
      schema:
        type: string
      description: The datatype of a SimpleReading's value property.
    - $ref: '#/components/parameters/offsetParam'
    - $ref: '#/components/parameters/limitParam'
    get:
      summary: Returns a paginated list of SimpleReadings whose value property is of the specified type.
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/SimpleReadingResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SimpleReadingResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SimpleReadingResponse'
        '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/SimpleReadingResponse'
  /reading/start/{start}/end/{end}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: start
        in: path
        required: true
        schema:
          type: integer
        description: "Unix timestamp indicating the start of a date/time range"
      - name: end
        in: path
        required: true
        schema:
          type: integer
        description: "Unix timestamp indicating the end of a date/time range"
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Return a paginated range of readings with a create date inside the specified start/end values."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/ReadingResponse'
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadingResponse'
        '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/ReadingResponse'