openapi: 3.0.0
info:
  title: EdgeX Foundry - Device Service API
  description: This is the definition of the API for Device services in the EdgeX Foundry IOT microservice platform. Device Services are responsible for obtaining Readings from target devices, and for writing values (settings) to them.
  version: 4.0.0

servers:
  - url: http://0:49999/api/v3
    description: URL for local development and testing

components:
  schemas:
    AutoEvent:
      description: "Identifies a resource which will be read automatically by the device service."
      type: object
      properties:
        interval:
          description: "Specifies a time interval between reading requests. This may be in a combination of hours, minutes, seconds and milliseconds (h/m/s/ms)"
          type: string
          example: "1m30s"
        onChange:
          description: "If true, new Events will only be generated if successive readings differ in value."
          type: boolean
        sourceName:
          description: "SourceName indicates the name of the resource or device command in the device profile which describes the event to generate"
          type: string
      required:
        - sourceName
        - frequency
    BaseRequest:
      description: "Defines basic properties which all use-case specific request DTO instances should support."
      type: object
      properties:
        requestId:
          description: "Uniquely identifies this request. For implementation, recommend this value be generated by the type's constructor."
          type: string
          format: uuid
          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
          example: "v3"
      required:
        - apiVersion
    BaseResponse:
      description: "Defines basic properties which all use-case specific response DTO instances should support"
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
          example: "v3"
        requestId:
          description: "Uniquely identifies the request that resulted 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
    Device:
      description: "A device is an IoT object represented in EdgeX."
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "The unique identifier of the device"
        name:
          type: string
          description: "The name of the device"
        description:
          type: string
          description: "A free-format descriptive field for additional device information"
        adminState:
          type: string
          enum: [LOCKED, UNLOCKED]
          description: "Administrative state of the device, allowing it to be locked for policy reasons"
        operatingState:
          type: string
          enum: [UP, DOWN, UNKNOWN]
          description: "Operating state of the device, indicating whether it is currently responsive"
        labels:
          type: array
          items:
            type: string
          description: "Other labels applied to the device to help with searching"
        location:
          type: object
          description: "Device service specific location information"
        serviceName:
          type: string
          description: "Associated device service referenced by name"
        profileName:
          type: string
          description: "Associated device profile referenced by name"
        autoEvents:
          type: array
          items:
            $ref: '#/components/schemas/AutoEvent'
          description: "Events which the service should generate automatically from this device."
        protocols:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ProtocolProperties'
        tags:
          type: object
          description: "A map of tags used to tag the given device."
        properties:
          type: object
          description: "A map of properties required to address the given device."
    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:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        id:
          description: "The unique identifier for the reading"
          type: string
          format: uuid
        created:
          description: "A Unix timestamp indicating when (if) the reading was initially persisted to a database."
          type: integer
        origin:
          description: "A Unix timestamp indicating when the reading was originated at the source device (can support nanoseconds)"
          type: integer
        deviceName:
          description: "The name of the device from which the reading originated"
          type: string
        resourceName:
          description: "The device resource name for the reading"
          type: string
        profileName:
          description: "The device profile name for the reading"
          type: string
        valueType:
          description: "Indicates the datatype of the value property"
          type: string
      required:
        - deviceName
        - resourceName
        - profileName
        - origin
        - valueType
    SimpleReading:
      description: "An event reading for a simple data type"
      allOf:
        - $ref: '#/components/schemas/BaseReading'
        - type: object
          properties:
            value:
              description: "A string representation of the reading's value"
              type: string
      required:
        - value
    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
          required:
            - binaryValue
            - mediaType
    Event:
      description: "A discrete event containing one or more readings"
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        id:
          description: "The unique identifier for the event"
          type: string
          format: uuid
        deviceName:
          description: "The name of the device from which the event originated"
          type: string
        profileName:
          description: "The name of the device profile from which the event originated"
          type: string
        created:
          description: "A Unix timestamp indicating when (if) the event was initially persisted to a database."
          type: integer
        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:
            oneOf:
              - $ref: '#/components/schemas/SimpleReading'
              - $ref: '#/components/schemas/BinaryReading'
        tags:
          description: "List of zero or more Tags attached to the Event which give more context to the Event"
          title: tags
          type: object
          example:
            Gateway-id: "HoustonStore-000123"
            Latitude: "29.630771"
            Longitude: "-95.377603"
      required:
        - id
        - deviceName
        - profileName
        - origin
        - readings
    EventResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
      description: "A response type for returning an Event to the caller."
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
      description: "A response type for returning a generic error to the caller."
      type: object
    ConfigResponse:
      description: "Provides a response containing the configuration for the targeted service."
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
        config:
          description: "An object containing the service''s configuration. Please refer to Core Data''s configuration documentation for more details at [EdgeX Foundry Documentation](https://docs.edgexfoundry.org)."
          type: object
    DeviceValidationRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
      description: "Notification that a new device associated with this device service has been created."
      type: object
      properties:
        device:
          $ref: '#/components/schemas/Device'
      required:
        - device
    PingResponse:
      description: "A response from the /ping endpoint indicating that the service is functioning."
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        timestamp:
          description: "Outputs the current server timestamp in RFC1123 format"
          example: "Mon, 02 Jan 2006 15:04:05 MST"
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
    ProtocolProperties:
      description: "The properties required to address a device via a particular protocol."
      example: {"Host":"floor4.hq.acme.com", "Port":"8080"}
      type: object
      additionalProperties:
        type: string
    SecretRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
      description: Defines the secret data to be stored
      type: object
      properties:
        secretName:
          description: Specifies the name of the secret
          type: string
          example: "credentials"
        secretData:
          description: A list of the key/value pairs of secret data to store
          type: array
          items:
            $ref: '#/components/schemas/SecretDataKeyValue'
      required:
        - secretName
        - secretData
    SecretDataKeyValue:
      description: Defines a key/value pair of the secret data
      type: object
      properties:
        key:
          description: The key to identify the secret
          type: string
          example: "username"
        value:
          description: The value of the secret
          type: string
          example: "mqtt-user"
      required:
        - key
        - value
    SettingRequest:
      description: "Defines new values to be written to device resources, as part of an actuation (put) command to a device"
      additionalProperties:
        type: string
      title: Setting
      type: object
      example: {"AHU-TargetTemperature": "28.5", "AHU-TargetBand": "4.0"}
    VersionResponse:
      description: "A response returned from the /version endpoint whose purpose is to report out the latest version supported by the service."
      type: object
      properties:
        apiVersion:
          description: "A version number shows the API version in DTOs."
          type: string
        version:
          description: "The latest version supported by the service."
          type: string
        sdk_version:
          description: "The version of the SDK with which the service was built."
          type: string
        serviceName:
          description: "Outputs the name of the service the response is from"
          type: string
    ProfileScanRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
      description: Defines the information for the profile scan
      type: object
      properties:
        deviceName:
          description: Specifies the device to generate the profile
          type: string
          example: "Test-Device"
        profileName:
          description: Specifies the unique profile name. Default format is {deviceName}_profile_{timestamp}
          type: string
          example: "Test-Device_profile_1720169510"
        options:
          type: object
          example:
            DiscoverMode: "All"
            DiscoverProperties: [ 103, 117 ]
            DiscoverObjects: [ 1, 2, 3, 4, 5]
      required:
        - deviceName

  parameters:
    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
      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"

  examples:
    400Example:
      value:
        apiVersion: "v3"
        requestId: "4c57bd0b-1cee-4056-8a8a-98eea8d999c6"
        statusCode: 400
        message: "Bad Request"
    404Example:
      value:
        apiVersion: "v3"
        requestId: "afe9a1f4-bc45-434c-6eb2-105440912368"
        statusCode: 404
        message: "Not Found"
    405Example:
      value:
        apiVersion: "v3"
        requestId: "e6e8a2f9-eb14-4649-9e2b-175247911369"
        statusCode: 405
        message: "Method Not Allowed"
    423Example:
      value:
        apiVersion: "v3"
        requestId: "8a41b3f4-0148-11eb-adc1-0242ac120002"
        statusCode: 423
        message: "Locked"
    500Example:
      value:
        apiVersion: "v3"
        requestId: "cd319159-928c-4a6f-9d3d-a821c524ac35"
        statusCode: 500
        message: "Internal Server Error"

paths:
  /device/name/{name}/{command}:
    get:
      description: Request the device/sensor by its name to return the current (or in some cases new) event/reading values for the command or device resource specified. The device service may have cached the latest event/reading for the sensor(s) or it may immediate request new event/reading values depending on the implementation and the device(s)/sensor(s) capability.
      parameters:
        - $ref: '#/components/parameters/correlatedRequestHeader'
        - in: path
          name: name
          required: true
          schema:
            type: string
          example: sensor01
          description: "A name uniquely identifying a device."
        - in: path
          name: command
          required: true
          schema:
            type: string
          example: command01
          description: "A name uniquely identifying a command."
        - in: query
          name: ds-pushevent
          schema:
            type: string
            enum:
              - true
              - false
            default: false
          example: true
          description: "If set to true, a successful GET will result in an event being pushed to the EdgeX system"
        - in: query
          name: ds-returnevent
          schema:
            type: string
            enum:
              - true
              - false
            default: true
          example: false
          description: "If set to false, there will be no Event returned in the http response"
        - in: query
          name: ds-regexcmd
          schema:
            type: string
            enum:
              - true
              - false
            default: true
          example: false
          description: "If set to false, the command name will be treated as normal string instead of regex syntax"
      responses:
        '200':
          description: String as returned by the device/sensor through the device service.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/EventResponse'
        '404':
          description: If no device exists by the name provided or the command is unknown.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                404Example:
                  $ref: '#/components/examples/404Example'
        '405':
          description: If the requested command exists but not for GET, or the resource is marked as write-only.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                405Example:
                  $ref: '#/components/examples/405Example'
        '423':
          description: If the device or service is locked (admin state), disabled (operating state), or lacks associated profile.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                423Example:
                  $ref: '#/components/examples/423Example'
        '500':
          description: The device driver is unable to process the request, or too many values were returned.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
    put:
      description: Request the actuator by its name to trigger a action or set a current value for the command or device resource specified.
      parameters:
        - $ref: '#/components/parameters/correlatedRequestHeader'
        - in: path
          name: name
          required: true
          schema:
            type: string
          example: sensor
        - in: path
          name: command
          required: true
          schema:
            type: string
          example: allValues
      responses:
        '200':
          description: The PUT command was successful.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "48395596-9f75-4556-97b4-8a834d26c1c7"
                statusCode: 200
        '404':
          description: If no device exists for the name provided or the command is unknown.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                404Example:
                  $ref: '#/components/examples/404Example'
        '405':
          description: If the requested command exists but not for PUT, or the resource is marked as read-only.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                405Example:
                  $ref: '#/components/examples/405Example'
        '423':
          description: If the device or service is locked (admin state) or disabled (operating state).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                423Example:
                  $ref: '#/components/examples/423Example'
        '500':
          description: The device driver is unable to process the request.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingRequest'
        required: true

  /secret:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: Stores a secret to the secure Secret Store
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/SecretRequest'
        required: true
      responses:
        '201':
          description: "Created"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "9dab3997-b399-4630-972c-d4ffa571f1f2"
                statusCode: 201
        '400':
          description: "Invalid request."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/400Example'
        '500':
          description: "An unexpected error happened on the server."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'

  /discovery:
    post:
      description: Run the discovery request for a Device Service. No request body is required.
      responses:
        '202':
          description: The service is running the discovery request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 202
                message: "Device Discovery is triggered"
        '423':
          description: The service is disabled or administratively locked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                423Example:
                  $ref: '#/components/examples/423Example'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
        '503':
          description: Discovery is disabled by configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "e1abba6d-7263-4046-9fe0-ef5b42e24bf2"
                statusCode: 503
                message: "HTTP request timeout"
    delete:
      summary: "Stop the ongoing device discovery process"
      parameters:
        - $ref: '#/components/parameters/correlatedRequestHeader'
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "9dae40d3-902f-49e5-b532-1b20d36d1f05"
                statusCode: 200
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
        '501':
          description: Request is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 501
                message: "Not implemented"

  /discovery/requestId/{requestId}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: requestId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: "An ID of datatype string, by default a GUID."
    delete:
      summary: "Stop the ongoing device discovery process with the specified request id"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "9dae40d3-902f-49e5-b532-1b20d36d1f05"
                statusCode: 200
        '404':
          description: If the specified request id does not match the current working request id.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                404Example:
                  $ref: '#/components/examples/404Example'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
        '501':
          description: Request is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 501
                message: "Not implemented"

  /profilescan:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      description: Run the discovery request to generate a associated device profile for a specified device.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ProfileScanRequest'
        required: true
      responses:
        '202':
          description: "Request has been accepted"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 202
                message: "Device ProfileScan is triggered"
        '400':
          description: "Request is in an invalid state"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "73f0932c-0148-11eb-adc1-0242ac120002"
                statusCode: 400
                message: "Bad Request"
        '404':
          description: "The requested resource does not exist."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/404Example'
        '409':
          description: "Conflict detected. Profile name must be universally unique or previous request is still processing."
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "8a41b3f4-0148-11eb-adc1-0242ac120002"
                statusCode: 409
                message: "Data Duplicate"
        '423':
          description: The device service is locked (admin state).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                423Example:
                  $ref: '#/components/examples/423Example'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
        '501':
          description: Request is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 501
                message: "Not implemented"

  /profilescan/device/name/{name}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: "Uniquely identifies a given device"
    delete:
      summary: "Stop the ongoing device profile scanning process for a specific device"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                apiVersion: "v3"
                requestId: "51e41bac-e405-4ee8-ad66-7741eb1e7b6d"
                statusCode: 200
        '404':
          description: "The requested resource does not exist."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400Example:
                  $ref: '#/components/examples/404Example'
        '423':
          description: The device service is locked (admin state).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                423Example:
                  $ref: '#/components/examples/423Example'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'
        '501':
          description: Request is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                apiVersion: "v3"
                requestId: "e6e8a2f4-eb14-4649-9e2b-175247911369"
                statusCode: 501
                message: "Not implemented"
  /config:
    get:
      summary: "Returns the current configuration of the service."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        '500':
          description: Interval Server Error
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'

  /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'
              example:
                apiVersion: "v3"
                timestamp: "Mon, 02 Jan 2006 15:04:05 MST"
                serviceName: "device-gps"
        '500':
          description: Interval Server Error
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'

  /version:
    get:
      summary: "A simple 'version' endpoint that will return the current version of the service"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
              example:
                apiVersion: "v3"
                version: "4.0.0"
                "sdk_version": "4.0.0"
                serviceName: "device-gps"
        '500':
          description: Interval Server Error
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500Example:
                  $ref: '#/components/examples/500Example'