notification-as-cloud-event.yaml

openapi: 3.0.3
info:
  title: Event Notification using CloudEvents specifications
  description: |
    The event notification endpoint is used by the API server to notify the API consumer that an event occurred.  The notification is the message posted on listener side.

    # Introduction

    A lot of CAMARA APIs offer the capability to API consumer to receive events.
    Event data are defined in each API definition but in order to provide consistency across CAMARA APIs and to increase 
    interoperability we will use [cloudevents](https://cloudevents.io/) specifications. In particular, every CAMARA Event will 
    be defined using [cloudevents-json-format](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md)
   
    # Relevant terms and definitions

      * **Occurrence** : An "occurrence" is the capture of a statement of fact during the operation of a software system.
  
      * **Event**: An "event" is a data record expressing an occurrence and its context. Events are routed from an 
    event producer (the source) to interested event consumers.
    
      * **Producer**: The "producer" is a specific instance, process or device that creates the data structure 
    describing the CloudEvent.
  
      * **Source**:  The "source" is the context in which the occurrence happened. In a distributed system it might 
    consist of multiple producers. If a source is not aware of CloudEvents, an external producer creates 
    the CloudEvent on behalf of the source.
  
      * **Consumer**: A "consumer" receives the event and acts upon it. It uses the context and data to execute some 
    logic, which might lead to the occurrence of new events.
  
      * **Data**:  Domain-specific information about the occurrence (i.e. the payload). This might 
    include information about the occurrence, details about the data that was changed, or more.
  
    # API Functionality
    
    Only one endpoint/operation is provided: `POST /your_webhook_notification_url`
    This endpoint describes the event notification received on subscription listener side when the event occurred. A detailed description of the event notification is provided in the CAMARA API design guideline document.

  termsOfService: http://swagger.io/terms/
  contact:
    email: project-email@sample.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.2.0-alpha.1
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/
security:
    - notificationsBearerAuth: []
    - {}

servers:
  - url: '{apiRoot}'
    variables:
      apiRoot:
        default: https://localhost:8080
        description: Can be any notification server address sent by the client application
tags:
  - name: CAMARA Cloud Event
    description: |
      Events received on subscription listener side.
paths:
  /your_webhook_notification_url:
    post:
      tags:
        - CAMARA Cloud Event
      summary: "Cloud Event notification endpoint to notify consumer that statement of fact had occurred"
      description: |
        INFORMATIVE ENDPOINT: The value of this endpoint is freely declared by each client app by means of resource-based
        subscription or instance-based subscription. /your_webhook_notification_url is 
        just a convention naming referring to an absolute URL, indeed the one indicated by API client
        in the triggering of the procedure (resource-based or instance-based).  In this way, it represents an absolute
        URL, i.e.: notifications won't be sent to /event-notification/vX/your_webhook_notification_url.
      operationId: sendEvent
      parameters:
        - $ref: "#/components/parameters/x-correlator"
      requestBody:
        required: true
        content:
          application/cloudevents+json:
            schema:
              $ref: "#/components/schemas/CloudEvent"
            examples:
              QOS_STATUS_CHANGED_EXAMPLE:
                $ref: '#/components/examples/QOS_STATUS_CHANGED_EXAMPLE'

      responses:
        204:
          description: No Content
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
        400:
          $ref: "#/components/responses/Generic400"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        410:
          $ref: "#/components/responses/Generic410"
        429:
          $ref: "#/components/responses/Generic429"
components:
  securitySchemes:
    notificationsBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
  schemas:
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description

    DateTime:
      type: string
      format: date-time
      description: |
        Timestamp of when the occurrence happened. Must adhere to RFC 3339. 
        WARN: This optional field in CloudEvents specification is required in CAMARA APIs implementation.
      example: '2018-04-05T17:31:00Z'

    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: |
        Identifies the context in which an event happened - be a non-empty `URI-reference` like:
        - URI with a DNS authority:
          * https://github.com/cloudevents
          * mailto:cncf-wg-serverless@lists.cncf.io
        - Universally-unique URN with a UUID:
          * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
        - Application-specific identifier:
          * /cloudevents/spec/pull/123
          * 1-555-123-4567
      example: "https://notificationSendServer12.supertelco.com"

    CloudEvent:
      description: The notification callback
      required:
        - id
        - source
        - specversion
        - type
        - time
      properties:
        id:
          type: string
          description: identifier of this event, that must be unique in the source context.
          minLength: 1
        source:
          $ref: '#/components/schemas/Source'
        type:
          type: string
          description: 'type of event as defined in each CAMARA API (e.g.: org.camaraproject.qod.qos-status-changed-event)'
          example: 'org.camaraproject.qod.qos-status-changed-event'
          minLength: 25
        specversion:
          type: string
          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
          enum:
            - "1.0"
        datacontenttype:
          type: string
          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
          enum:
            - application/json
        data:
          type: object
          description: Event details payload described in each CAMARA API and referenced by its type
        time:
          $ref: "#/components/schemas/DateTime"
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string

  responses:
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 400
            code: "INVALID_ARGUMENT"
            message: "Client specified an invalid argument, request body or query param"
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 401
            code: "UNAUTHENTICATED"
            message: "Request not authenticated due to missing, invalid, or expired credentials"
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 403
            code: "PERMISSION_DENIED"
            message: "Client does not have sufficient permissions to perform this action"
    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 410
            code: GONE
            message: "Access to the target resource is no longer available."
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 429
            code: TOO_MANY_REQUESTS
            message: "Endpoint does not support as many requests per time slot"
    Generic500:
      description: Server error
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 500
            code: "INTERNAL"
            message: "Server error"
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 503
            code: "UNAVAILABLE"
            message: "Service unavailable"
  examples:
    QOS_STATUS_CHANGED_EXAMPLE:
      value:
        id: "123e4567-e89b-12d3-a456-426655440000"
        source: "https://notificationSendServer12.supertelco.com"
        type: "org.camaraproject.qod.qos-status-changed-event"
        specversion: "1.0"
        time: "2023-01-17T13:18:23.682Z"
        datacontenttype: "application/json"
        data:
          sessionId: "6e8bc430-9c3a-11d9-9669-0800200c9a66"
          qosStatus: UNAVAILABLE
          statusInfo: DURATION_EXPIRED