Add generic notification OAS file

artifacts/EventNotification-v0.1.0-wip.yaml

@@ -0,0 +1,253 @@
+openapi: 3.0.3
+info:
+  title: Event Notification
+  description: |
+    The event notification endpoint is used by the API server to notify the API consumer that an event occured.  The notification is the message posted on listener side.
+
+    # Introduction
+
+    A lot of CAMARA APIs offer the capability to consumer to receive event notification.
+    Event notification are defined in each API definition but in order to provide consistency accross CAMARA API a common event notification strucutre is provided.
+
+    # Relevant terms and definitions
+
+    * **eventType** : Type of event as defined in each CAMARA API (examples: ROAMING_STATUS, QOS_STATUS_CHANGED, PAYMENT_COMPLETED, etc...)
+
+    * **eventDetail** : Event details structure depending on the eventType and defined  in each CAMARA API.
+
+    # API Functionality   
+
+
+    Only one endpoint/operation is provided: `POST /notifications`
+
+    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.5.0-wip
+externalDocs:
+  description: Product documentation at CAMARA
+  url: https://github.com/camaraproject/
+security:
+  #  - {}
+  - oAuth2ClientCredentials: []
+  #  - BasicAuth: []
+  #  - apiKey: []
+servers:
+  - url: '{apiRoot}/{basePath}'
+    variables:
+      apiRoot:
+        default: http://localhost:9091
+        description: API root
+      basePath:
+        default: /event-notification/v0
+        description: Base path for the event notifiation API
+tags:
+  - name: Event Notification
+    description: |
+      Notification received on subscription listener side. 
+paths:
+  /eventNotifications:
+    post:
+      tags:
+        - Event Notification
+      summary: "Notification endpoint to notify listener that an event had occurred"
+      description: Notification endpoint to notify listener that an event occurred. This endpoint must be exposed on the listener side.
+      operationId: postNotification
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EventNotification"
+            examples:
+              EVENT_EXEMPLE:
+                $ref: '#/components/examples/EVENT_EXEMPLE'
+
+      responses:
+        204:
+          description: No Content
+        400:
+          $ref: "#/components/responses/Generic400"
+        401:
+          $ref: "#/components/responses/Generic401"
+        403:
+          $ref: "#/components/responses/Generic403"
+        500:
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorInfo"
+        503:
+          $ref: "#/components/responses/Generic503"
+components:
+  securitySchemes:
+    oAuth2ClientCredentials:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: '{tokenUrl}'
+          scopes: {}
+    #    BasicAuth:
+    #      type: http
+    #      scheme: basic
+    #    apiKey:
+    #      type: apiKey
+    #      description: API key to authorize requests
+    #      name: apikey
+    #      in: query
+    three_legged:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.example.com/authorize
+          tokenUrl: https://auth.example.com/token
+          scopes:
+            device-status-roaming-read: Read device roaming status
+  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
+
+
+    EventSubscriptionId:
+      type: string
+      description: The event subscription identifier.
+
+    EventTime:
+      format: date-time
+      type: string
+      description: The time when the event was notified.
+
+    EventNotification:
+      description: The notification callback.
+      type: object
+      required:
+        - event
+      properties:
+        eventSubscriptionId:
+          $ref: '#/components/schemas/EventSubscriptionId'
+        event:
+          $ref: '#/components/schemas/Event'
+
+    Event:
+      description: Generic event structure
+      required:
+        - eventType
+        - eventTime
+        - eventDetail
+      properties:
+        eventType:
+          type: string
+        eventTime:
+          $ref: '#/components/schemas/EventTime'
+        eventId:
+          type: string
+          format: uuid
+        eventDetail:
+          type: object
+      discriminator:
+        propertyName: 'eventType'
+
+
+  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"
+    Generic404:
+      description: Resource Not Found
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: NOT_FOUND
+            message: "The specified resource is not found"
+    Generic409:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: CONFLICT
+            message: "The specified resource is in a conflict"
+    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:
+    EVENT_EXEMPLE:
+      value:
+        eventSubscriptionId: 123654
+        event:
+          eventType: EVENT_TYPE_AS_DEFINED_IN_EACH_API
+          eventTime: 2023-01-17T13:18:23.682Z
+          eventDetail:
+            eventDetailAttribute1:
+              eventDetailAttribute2: 123456789
+            eventDetailAttribute3: true
+            eventDetailAttribute4: ....

documentation/API-design-guidelines.md

@@ -1017,6 +1017,7 @@ This part describes the list of possible messages returned by the API. It also i
 This part captures a detailed description of all the data structures used in the API specification. For each of these data, the specification must contain:
 - Name of the data object, used to reference it in other sections.
 - Data type (String, Integer, Object…).
+- If the format of a string is datetime following sentence must be present in the description: `It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`
 - If the data type is an object, list of required properties.
 - List of properties within the object data, including:
    - Property name