Subscription & events for Commonalities 0.5.0

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

@@ -4,6 +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 combined usage of `initialEvent` and `subscriptionMaxEvents`:
+    If an event is triggered following `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents` (if provided).
+
     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.
 
   license:
@@ -16,14 +19,13 @@ 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
@@ -98,7 +100,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Subscription"
+                $ref: "#/components/schemas/SubscriptionCreationResponse"
         "202":
           description: Request accepted to be processed. It applies for async creation process.
           headers:
@@ -116,8 +118,6 @@ paths:
           $ref: "#/components/responses/SubscriptionPermissionDenied403"
         "409":
           $ref: "#/components/responses/Generic409"
-        "415":
-          $ref: "#/components/responses/Generic415"
         "422":
           $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422"
         "429":
@@ -460,6 +460,15 @@ components:
         - org.camaraproject.api-name.v0.event-type
         - org.camaraproject.api-name.v0.subscription-ends
 
+    SubscriptionCreationResponse:
+      description: Response for the POST request
+      type: object
+      required:
+        - id
+      properties:
+        id:
+          $ref: '#/components/schemas/SubscriptionId'
+
     Subscription:
       description: Represents a event-type subscription.
       type: object
@@ -477,8 +486,6 @@ components:
           format: url
           description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
-        sinkCredential:
-          $ref: '#/components/schemas/SinkCredential'
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
@@ -900,12 +907,6 @@ components:
                 status: 403
                 code: PERMISSION_DENIED
                 message: Client does not have sufficient permissions to perform this action.
-            GENERIC_403_INVALID_TOKEN_CONTEXT:
-              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
-              value:
-                status: 403
-                code: INVALID_TOKEN_CONTEXT
-                message: "{{field}} is not consistent with access token."
             GENERIC_403_SUBSCRIPTION_MISMATCH:
               value:
                 status: 403
@@ -965,22 +966,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:
@@ -1008,6 +993,18 @@ components:
                 status: 422
                 code: DEVICE_NOT_APPLICABLE
                 message: The service is not available for the provided device.
+            GENERIC_422_UNNECESSARY_IDENTIFIER:
+              description: An explicit identifier is provided when an API subject has already been identified from the access token
+              value:
+                status: 422
+                code: UNNECESSARY_IDENTIFIER
+                message: The device is already identified by the access
+            GENERIC_422_MISSING_IDENTIFIER:
+              description: An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token
+              value:
+                status: 422
+                code: MISSING_IDENTIFIER
+                message: The device cannot be identified
     Generic429:
       description: Too Many Requests
       headers: