Subscription & events for Commonalities 0.5.0

artifacts/camara-cloudevents/event-subscription-template.yaml

@@ -4,7 +4,9 @@ info:
   description: |
     This file is a template for CAMARA API explicit subscription endpoint and for Notification model. Additional information are provided in API Design Guidelines document.
 
-    Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type:grant-level` must be replaced accordingly to the format defined in the guideline document.
+    Note on event name convention: the event type name MUST follow: ``org.camaraproject.<api-name>.<api-version>.<event-name>``
+
+    Note on ``security`` - ``openId`` scope: The value in this yaml `api-name:event-type1:grant-level` must be replaced accordingly to the format defined in the guideline document.
 
   license:
     name: Apache 2.0
@@ -16,14 +18,12 @@ externalDocs:
   description: Product documentation at CAMARA
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/{apiName}/v0.1"
+  - url: "{apiRoot}/api-name/vx.y"
+  # api-name and version should valued accordingly to the API
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root
-      apiName:
-        default: camaraAPI
-        description: apiName will be replaced in WG by its value and not modelled as a variable
+        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
 tags:
   - name: <apiName> Subscription
     description: Operations to manage event subscriptions on event-type event
@@ -40,7 +40,8 @@ paths:
         - $ref: "#/components/parameters/x-correlator"
       security:
         - openId:
-            - api-name:event-type:grant-level
+            - api-name:event-type1:grant-level
+            - api-name:event-type2:grant-level
       requestBody:
         content:
           application/json:
@@ -81,10 +82,6 @@ paths:
                   $ref: "#/components/responses/Generic410"
                 "429":
                   $ref: "#/components/responses/Generic429"
-                "500":
-                  $ref: "#/components/responses/Generic500"
-                "503":
-                  $ref: "#/components/responses/Generic503"
               security:
                 - {}
                 - notificationsBearerAuth: []
@@ -116,16 +113,10 @@ paths:
           $ref: "#/components/responses/SubscriptionPermissionDenied403"
         "409":
           $ref: "#/components/responses/Generic409"
-        "415":
-          $ref: "#/components/responses/Generic415"
         "422":
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
           $ref: "#/components/responses/Generic429"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     get:
       tags:
         - <apiName> Subscription
@@ -156,10 +147,6 @@ paths:
           $ref: "#/components/responses/Generic401"
         "403":
           $ref: "#/components/responses/Generic403"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
   /subscriptions/{subscriptionId}:
     get:
       tags:
@@ -191,10 +178,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
     delete:
       tags:
         - <apiName> Subscription
@@ -230,10 +213,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         "404":
           $ref: "#/components/responses/Generic404"
-        "500":
-          $ref: "#/components/responses/Generic500"
-        "503":
-          $ref: "#/components/responses/Generic503"
 components:
   securitySchemes:
     openId:
@@ -301,13 +280,12 @@ components:
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
-            Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
-             at API project level.
+            Note: for the current Commonalities version (v0.5) only one event type per subscription is allowed, yet in the following releases use of array of event types SHALL be specified without changing this definition.
           type: array
           minItems: 1
           maxItems: 1
           items:
-            type: string
+            $ref: "#/components/schemas/SubscriptionEventType"
         config:
           $ref: "#/components/schemas/Config"
       discriminator:
@@ -453,13 +431,22 @@ components:
     EventTypeNotification:
       type: string
       description: |
-        event-type - Event triggered when an event-type event occurred
+        event-type - Event triggered when an event-type event occurred. Several event-type could be defined.
 
         subscription-ends: Event triggered when the subscription ends
       enum:
-        - org.camaraproject.api-name.v0.event-type
+        - org.camaraproject.api-name.v0.event-type1
+        - org.camaraproject.api-name.v0.event-type2
         - org.camaraproject.api-name.v0.subscription-ends
 
+    SubscriptionEventType:
+      type: string
+      description: |
+        event-type that could be subscribed through this subscription. Several event-type could be defined.
+      enum:
+        - org.camaraproject.api-name.v0.event-type1
+        - org.camaraproject.api-name.v0.event-type2
+
     Subscription:
       description: Represents a event-type subscription.
       type: object
@@ -572,7 +559,8 @@ components:
       discriminator:
         propertyName: "type"
         mapping:
-          org.camaraproject.api-name.v0.event-type: "#/components/schemas/Event-typeEvent"
+          org.camaraproject.api-name.v0.event-type1: "#/components/schemas/EventApiSpecific1"
+          org.camaraproject.api-name.v0.event-type2: "#/components/schemas/EventApiSpecific2"
           org.camaraproject.api-name.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds"
 
     Source:
@@ -597,8 +585,14 @@ components:
       description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
       example: "2018-04-05T17:31:00Z"
 
-    Event-typeEvent:
-      description: event structure for event-type event
+    EventApiSpecific1:
+      description: event structure for event-type event 1
+      allOf:
+        - $ref: "#/components/schemas/CloudEvent"
+        - type: object
+
+    EventApiSpecific2:
+      description: event structure for event-type event 2
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
@@ -965,22 +959,6 @@ components:
                 status: 410
                 code: GONE
                 message: Access to the target resource is no longer available.
-    Generic415:
-      description: Unsupported Media Type
-      headers:
-        X-Correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
-              description: Payload format of the request is in an unsupported format by the Server. Should not happen
-              value:
-                status: 415
-                code: UNSUPPORTED_MEDIA_TYPE
-                message: The server refuses to accept the request because the payload format is in an unsupported format
     CreateSubscriptionUnprocessableEntity422:
       description: Unprocessable Entity
       headers:
@@ -1030,38 +1008,6 @@ components:
                 status: 429
                 code: TOO_MANY_REQUESTS
                 message: Either out of resource quota or reaching rate limiting.
-    Generic500:
-      description: Server error
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorInfo"
-          examples:
-            GENERIC_500_INTERNAL:
-              description: Problem in Server side. Regular Server Exception
-              value:
-                status: 500
-                code: INTERNAL
-                message: Unknown server error. Typically a server bug.
-    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"
-          examples:
-            GENERIC_503_UNAVAILABLE:
-              description: Service is not available. Temporary situation usually related to maintenance process in the server side
-              value:
-                status: 503
-                code: UNAVAILABLE
-                message: Service Unavailable.
     SubscriptionIdRequired:
       description: Problem with the client request
       headers: