support-notifications.yaml

openapi: 3.0.0
info:
  title: Edgex Foundry - Support Notifications API
  description: This is the definition of the API for the Support Notifications service in the EdgeX Foundry IOT microservice platform. Support Notifications provides functionality for sending notifications via email/REST from the EdgeX Foundry platform.
  version: 2.x
  
servers:
  - url: http://localhost:48060/api/v2
    description: URL for local development and testing
  
components:
  schemas:
    AddNotificationRequest:
      allOf:
      - $ref: '#/components/schemas/CorrelatedRequest'
      type: object
      properties:
        category:
          description: "Categorizes the notification. Must be one of three values: SECURITY, HW_HEALTH, SW_HEALTH"
        content:
          description: "The actual content to be sent as the body of the notification."
          type: string
        contentType:
          description: "Indicates the MIME type/Content-type of the notification's content."
          type: string
        description:
          description: "An optional description of the notification's intent."
          type: string
        labels:
          description: "Arbitrary labels that can be applied to notifications for further categorization or identification."
          type: array
          items:
            type: string
        sender:
          description: "Identifies the sender of a notification, usually an email address."
          type: string
        severity:
          description: "Indicates the level of severity for the notification. Current accepted values include: NORMAL, CRITICAL"
          type: string
        slug:
          description: "Effectively a name or key that labels the notification."
          type: string
        status:
          description: "A status indicating the current processing status of the notification. This should be set to NEW when adding a notification."
          type: string
      required:
      - category
      - content
      - sender
      - severity
      - slug
    AddNotificationResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
    AddSubscriptionRequest:
      allOf:
      - $ref: '#/components/schemas/CorrelatedRequest'
      type: object
      properties:
        categories:
          description: "Links the subscription to one or more categories of notification. Must be one of three values: SECURITY, HW_HEALTH, SW_HEALTH"
          type: array
          items:
            type: string
        channels:
          description: "Indicates how this subscription is capable of receiving notifications."
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        description:
          description: "An optional description of the subscription's intent."
          type: string
        labels:
          description: "Arbitrary labels that can be applied to the subscription for further categorization or identification."
          type: array
          items:
            type: string
        receiver:
          description: "The name of the party interested in the notification."
          type: string
        slug:
          description: "Links the subscription to the name or key that labels the notification of interest."
          type: string
      required:
      - channels
      - receiver
      - slug
    AddSubscriptionResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
    Channel:
      description: "Defines the transport supported for a given notification."
      type: object
      properties:
        emailAddresses:
          description: "If the transport is EMAIL, one or more email addresses that should receive the notification."
          type: array
          items:
            type: string
        type:
          description: "Indicates the type of transport to be used in delivering the notification. May be one of the following values: REST, EMAIL"
          type: string
        url:
          description: "If the transport is REST, the target URL to which the notification will be posted."
          type: string
    CleanupResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
    CorrelatedRequest:
      description: "Provides a correlation ID that can be used when grouping multiple requests into a single batch. For example, multiple notifications 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 notifications 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
    Notification:
      description: "Defines the content included in a notification"
      type: object
      properties:
        category:
          description: "Categorizes the notification. Must be one of three values: SECURITY, HW_HEALTH, SW_HEALTH"
        content:
          description: "The actual content to be sent as the body of the notification."
          type: string
        contentType:
          description: "Indicates the MIME type/Content-type of the notification's content."
          type: string
        created:
          description: "A timestamp indicating when the notification was created."
          type: integer
        description:
          description: "An optional description of the notification's intent."
          type: string
        id:
          description: "Uniquely identifies the notification"
          type: string
          format: uuid
        labels:
          description: "Arbitrary labels that can be applied to notifications for further categorization or identification."
          type: array
          items:
            type: string
        modified:
          description: "A timestamp indicating when the notification was last modified."
          type: integer
        sender:
          description: "Identifies the sender of a notification, usually an email address."
          type: string
        severity:
          description: "Indicates the level of severity for the notification. Current accepted values include: NORMAL, CRITICAL"
          type: string
        slug:
          description: "Effectively a name or key that labels the notification."
          type: string
        status:
          description: "A status indicating the current processing status of the notification. Accepted values are: NEW, PROCSSED, ESCALATED"
          type: string
    NotificationResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        notification:
          $ref: '#/components/schemas/Notification'
    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
    Subscription:
      description: "Define address information for a party interested in receiving notifications."
      type: object
      properties:
        categories:
          description: "Links the subscription to one or more categories of notification. Must be one of three values: SECURITY, HW_HEALTH, SW_HEALTH"
          type: array
          items:
            type: string
        channels:
          description: "Indicates how this subscription is capable of receiving notifications."
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        created:
          description: "A timestamp indicating when the subscription was created."
          type: integer
        description:
          description: "An optional description of the subscription's intent."
          type: string
        id:
          description: "Uniquely identifies the subscription"
          type: string
          format: uuid
        labels:
          description: "Arbitrary labels that can be applied to the subscription for further categorization or identification."
          type: array
          items:
            type: string
        modified:
          description: "A timestamp indicating when the subscription was last modified."
          type: integer
        receiver:
          description: "The name of the party interested in the notification."
          type: string
        slug:
          description: "Links the subscription to the name or key that labels the notification of interest."
          type: string
    SubscriptionResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/Subscription'
    Transmission:
      description: "Records an individual attempt to send a notification, whether successful or not."
      type: object
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
        created:
          description: "A timestamp indicating when the transmission was created."
          type: integer
        id:
          description: "Uniquely identifies the transmission"
          type: string
          format: uuid
        modified:
          description: "A timestamp indicating when the transmission was last modified."
          type: integer
        notification:
          $ref: '#/components/schemas/Notification'
        receiver:
          description: "The name of the party interested in the notification."
          type: string
        records:
          description: "Contains the result of all attempts to deliver this particular transmission."
          type: array
          items:
            $ref: '#/components/schemas/TransmissionRecord'
        resendCount:
          description: "Indicates how many time resend has been attempted for the transmission."
          type: integer
        status:
          description: "Indicates the most recent success/failure of a given transmission attempt. Accepted values are: ACKNOWLEDGED, FAILED, SENT, TRXESCALATED"
          type: string
    TransmissionRecord:
      description: "Records the result of an individual attempt to transmit a notification."
      type: object
      properties:
        status:
          description: "Indicates the success/failure of a given transmission attempt. Accepted values are: ACKNOWLEDGED, FAILED, SENT, TRXESCALATED"
          type: string
        response:
          description: "Records any response received when attempting the transmission. An HTTP error or SMTP failure will be logged here."
          type: string
        sent:
          description: "The timestamp of the transmission attempt."
          type: integer
    TransmissionResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        transmission:
          $ref: '#/components/schemas/Transmission'
    UpdateSubscriptionRequest:
      allOf:
      - $ref: '#/components/schemas/CorrelatedRequest'
      type: object
      properties:
        categories:
          description: "Links the subscription to one or more categories of notification. Must be one of three values: SECURITY, HW_HEALTH, SW_HEALTH"
          type: array
          items:
            type: string
        channels:
          description: "Indicates how this subscription is capable of receiving notifications."
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        description:
          description: "An optional description of the subscription's intent."
          type: string
        id:
          description: "Uniquely identifies the subscription"
          type: string
          format: uuid
        labels:
          description: "Arbitrary labels that can be applied to the subscription for further categorization or identification."
          type: array
          items:
            type: string
        receiver:
          description: "The name of the party interested in the notification."
          type: string
        slug:
          description: "Links the subscription to the name or key that labels the notification of interest."
          type: string
      required:
      - channels
      - id
      - receiver
      - slug
    UpdateSubscriptionResponse:
      allOf:
      - $ref: '#/components/schemas/CorrelatedResponse'
      type: object
      properties:
        id:
          type: string
          format: uuid
  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."
    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'
  /cleanup:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    delete:
      summary: "Delete all the Notifications if the current timestamp minus their last modification timestamp is less than a default age setting, and the corresponding Transmissions will also be deleted."
      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/CleanupResponse'
  /cleanup/age/{age}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: age
        in: path
        required: true
        schema:
          type: integer
        description: "Indicates the age of a notification in ticks"
    delete:
      summary: "Delete all the Notifications if the current timestamp minus their last modification timestamp is less than the age parameter, and the corresponding Transmissions will also be deleted."
      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/CleanupResponse'
  /notification:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: "Add one or more notifications - slug (name) must be unique on each request."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddNotificationRequest'
      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/AddNotificationResponse'
  /notification/start/{start}/end/{end}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: start
        in: path
        required: true
        schema:
          type: integer
        description: "The beginning timestamp of the range of notifications to be returned."
      - name: end
        in: path
        required: true
        schema:
          type: integer
        description: "The ending timestamp of the range of notifications to be returned."
    get:
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      summary: "Allows querying of notifications by their creation timestamp within a given time range, sorted in descending order. Results are paginated."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '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/NotificationResponse'
        '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/NotificationResponse'
  /notification/age/{age}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: age
        in: path
        required: true
        schema:
          type: integer
        description: "Indicates the age of a notification in ticks"
    delete:
      summary: "Delete the proccessed Notifications if the current timestamp minus their last modification timestamp is less than the age parameter, and the corresponding Transmissions will also be deteled.  Please notice this API is only for proccessed Notifications (status = PROCCESSED).  If the deletion purpose includes each kind of Notifications, please refer to /cleanup API."
      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/NotificationResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
  /notification/category/{category}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: category
        in: path
        required: true
        schema:
          type: string
        description: "The category of the notifications you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Notifications by category."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '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/NotificationResponse'
        '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/NotificationResponse'
  /notification/label/{label}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: label
        in: path
        required: true
        schema:
          type: string
        description: "The label of the notifications you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Notifications by label."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '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/NotificationResponse'
        '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/NotificationResponse'
  /notification/slug/{slug}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: "The slug (name) assigned to the notification of interest."
    get:
      summary: "Retrieve the notification associated with the provided slug (name)."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
    delete:
      summary: "Deletes the notification associated with the provided slug (name) and all of its associated transmissions."
      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/NotificationResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
  /notification/status/{status}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: status
        in: path
        required: true
        schema:
          type: string
        description: "The status of the notifications you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Notifications by current status"
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '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/NotificationResponse'
        '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/NotificationResponse'
  /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'
  /subscription:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
    post:
      summary: "Add one or more new subscriptions - slug (name) must be unique on each request."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddSubscriptionRequest'
      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/AddSubscriptionResponse'
    patch:
      summary: "Update one or more existing Subscriptions. You might do this in order to add an additional channel if you want another endpoint/person to receive the notification."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateSubscriptionRequest'
      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/UpdateSubscriptionResponse'
  /subscription/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Allows paginated retrieval of subscriptions, 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/SubscriptionResponse'
        '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/SubscriptionResponse'
  /subscription/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: "Allows retrieval of the subscription corresponding to the specified ID."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
    delete:
      summary: "Deletes a subscription according to the given 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/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
  /subscription/category/{category}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: category
        in: path
        required: true
        schema:
          type: string
        description: "The category of the subscriptions you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Subscriptions by category."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionResponse'
        '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/SubscriptionResponse'
        '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/SubscriptionResponse'
  /subscription/label/{label}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: label
        in: path
        required: true
        schema:
          type: string
        description: "The label of the subscriptions you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Subscriptions by label."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionResponse'
        '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/SubscriptionResponse'
        '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/SubscriptionResponse'
  /subscription/receiver/{receiver}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: receiver
        in: path
        required: true
        schema:
          type: string
        description: "The receiver of the subscriptions you wish to load."
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Query the Subscriptions by receiver."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionResponse'
        '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/SubscriptionResponse'
        '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/SubscriptionResponse'
  /subscription/slug/{slug}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: "The slug (name) given to the subscription of interest."
    get:
      summary: "Allows retrieval of the subscription corresponding to the specified slug (name)."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
    delete:
      summary: "Deletes a subscription according to the given slug (name)."
      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/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
  /transmission/age/{age}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: age
        in: path
        required: true
        schema:
          type: integer
        description: "Indicates the age of a transmission in ticks"
    delete:
      summary: "Delete the proccessed Transmissions if the current timestamp minus their last modification timestamp is less than the age parameter."
      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/TransmissionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransmissionResponse'
  /transmission/all:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
    get:
      summary: "Load all transmission records ordered by create timestamp descending. Results will be paginated."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransmissionResponse'
        '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/TransmissionResponse'
  /transmission/slug/{slug}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: "The slug (name) associated with a notification."
    get:
      summary: "Allows retrieval of the transmissions that originated with a notification identified by the slug. Ordered by create timestamp descending."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
  /transmission/start/{start}/end/{end}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - name: start
        in: path
        required: true
        schema:
          type: integer
        description: "The beginning timestamp of the range of transmissions to be returned."
      - name: end
        in: path
        required: true
        schema:
          type: integer
        description: "The ending timestamp of the range of transmissions to be returned."
    get:
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      summary: "Allows querying of transmissions by their creation timestamp within a given time range, sorted in descending order. Results are paginated."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransmissionResponse'
        '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/TransmissionResponse'
        '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/TransmissionResponse'
  /transmission/status/{status}:
    parameters:
      - $ref: '#/components/parameters/correlatedRequestHeader'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - name: status
        in: path
        required: true
        schema:
          type: string
        description: "The status of the transmissions you wish to load."
    get:
      summary: "Allows retrieval of the transmissions associated with the specified status. Ordered by create timestamp descending."
      responses:
        '200':
          description: "OK"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '404':
          description: "The requested resource does not exist"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '500':
          description: "An unexpected error occurred on the server"
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/correlatedResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'