Define CAMARA Event using cloudevents in OAS notification

artifacts/notification-as-cloud-event.yaml

@@ -0,0 +1,287 @@
+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: [email protected]
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+  version: 0.1.0
+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: Cloud Event
+    description: |
+      Events received on subscription listener side.
+paths:
+  /your_webhook_notification_url:
+    post:
+      tags:
+        - CAMARA Cloud Event notification endpoint
+      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
+      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:
+        201:
+          description: Created
+        202:
+          description: Accepted
+        204:
+          description: No Content
+        200:
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+        400:
+          $ref: "#/components/responses/Generic400"
+        401:
+          $ref: "#/components/responses/Generic401"
+        403:
+          $ref: "#/components/responses/Generic403"
+        410:
+          $ref: "#/components/responses/Generic410"
+        415:
+          $ref: "#/components/responses/Generic415"
+        429:
+          $ref: "#/components/responses/Generic429"
+        500:
+          $ref: "#/components/responses/Generic500"
+        503:
+          $ref: "#/components/responses/Generic503"
+components:
+  securitySchemes:
+    notificationsBearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
+  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:[email protected]
+        - 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)
+          minLength: 3
+        datacontenttype:
+          type: string
+          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
+        data:
+          type: object
+          description: Event details payload described in each CAMARA API and referenced by its type
+        time:
+          $ref: "#/components/schemas/DateTime"
+
+  responses:
+    Generic400:
+      description: Problem with the client request
+      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
+      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
+      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
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: GONE
+            message: "Access to the target resource is no longer available."
+    Generic415:
+      description: Unsupported Media Type
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: UNSUPPORTED_MEDIA_TYPE
+            message: "The specified media type is not supported"
+    Generic429:
+      description: Too Many Requests
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: TOO_MANY_REQUESTS
+            message: "Endpoint does not support as many requests per time slot"
+    Generic500:
+      description: Server error
+      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.
+      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
+