support-logging.yaml

openapi: 3.0.0
info:
  title: Edgex Foundry - Support Logging API
  description: This is the definition of the API for the Support Logging service in the EdgeX Foundry IOT microservice platform. Support Logging provides functionality to other services for use in logging. In the case where a client service isn't simply writing its logs to a file, it can make a call to Support Logging which then serves as an abstraction around the eventual persistence method for logs -- file, database, etc.
  version: 2.x
  
servers:
  - url: http://localhost:48061/api/v2
    description: URL for local development and testing
  
components:
  schemas:
    CorrelatedRequest:
      description: "Provides a correlation ID that can be used when grouping multiple requests into a single batch. For example, multiple log entries can be posted at once. Each entry 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 log entries 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
    LogEntry:
      description: "A model defining a basic log entry."
      type: object
      properties:
        level:
          description: "Defines the severity of the message being logged. Must be one of the following values -- TRACE, DEBUG, INFO, WARN, ERROR"
          type: string
        args:
          description: "An array of objects, effectively treated as strings, that will be output as a series of key/value pairs. Useful for timestamps, identifying the location of the logging statement in the code, etc."
          type: array
          items:
            type: object
        originService:
          description: "The service which generated the log entry"
          type: string
        message:
          description: "The primary message to be logged."
          type: string
        created:
          description: "Timestamp when the log entry was created."
          type: integer
      required:
      - level
      - originService
      - message
      - created
    LogEntryResponse:
      allOf:
        - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/LogEntry'
      required:
      - entry
    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
    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
    WriteLogEntryRequest:
      allOf:
      - $ref: '#/components/schemas/CorrelatedRequest'
      description: "A request to persist a given log entry"
      properties:
        entry:
          $ref: '#/components/schemas/LogEntry'
      required:
      - entry
    WriteLogEntryResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      description: "A response to the operation of persisting a given log entry. While logging is largely a fire-and-forget operation, this response will prove useful if there's an error we need to communicate back to the caller."
  parameters:
    offsetParam:
      in: query
      name: offset
      required: true
      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: true
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
      description: "The numbers of items to return."
    logLevelsParam:
      in: query
      name: levels
      required: false
      schema:
        type: string
      description: "A comma-delimited string of log levels, allowing queries to only return log entries associated with the specified severity."
      example: "TRACE, DEBUG"
    keywordsParam:
      in: query
      name: keywords
      required: false
      schema:
        type: string
      description: "A simple keyword search term that should be present in the log entries of interest. Grouping, wildcards and boolean operators are not supported."
    originServicesParam:
      in: query
      name: services
      required: false
      schema:
        type: string
      description: "A comma-delimited list of service keys indicating the services from which the log entries of interest originated."
      example: "edgex-core-data, edgex-core-command"
    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'
  /logs:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: "The endpoint for writing new log entries"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/WriteLogEntryRequest'
      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/WriteLogEntryResponse'
  /logs/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/logLevelsParam'
      - $ref: '#/components/parameters/keywordsParam'
      - $ref: '#/components/parameters/originServicesParam'
    get:
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      summary: "Allows paginated retrieval of log entries matching the specified parameters, sorted by created timestamp descending."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEntryResponse'
        '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/LogEntryResponse'
    delete:
      summary: "Allows deletion of log entries matching the specified parameters (levels, keywords, services, etc)"
      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/LogEntryResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogEntryResponse'
  /logs/start/{start}/end/{end}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/logLevelsParam'
      - $ref: '#/components/parameters/keywordsParam'
      - $ref: '#/components/parameters/originServicesParam'
      - name: start
        in: path
        required: true
        schema:
          type: integer
        description: "The beginning timestamp of the range of log entries to be returned."
      - name: end
        in: path
        required: true
        schema:
          type: integer
        description: "The ending timestamp of the range of log entries to be returned."
    get:
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      summary: "Allows paginated retrieval of log entries within a given time range, sorted by created timestamp descending."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEntryResponse'
        '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/LogEntryResponse'
        '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/LogEntryResponse'
    delete:
      summary: "Allows deletion of log entries within a given time range"
      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/LogEntryResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogEntryResponse'
  /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'