Invitation workflow for OCM, take 2

spec.yaml

@@ -27,7 +27,6 @@ parameters:
     description: >
       Default parameter to handle paging through collections. However, this
       parameter is NOT mandatory, as clients should use
-
       the HAL navigation links (e.g. `_links.next.href`) to paginate. These
       links enable the possibility to use vendor specific pagination.
 paths:
@@ -37,7 +36,6 @@ paths:
       description: >
         After the provider created a local share, it sends a `share` object to
         the consumer containing the 
-
         information which is needed to start synchronization between the two
         services.
       parameters:
@@ -49,7 +47,10 @@ paths:
             $ref: '#/definitions/NewShare'
       responses:
         '201':
-          description: Consumer successfully received the share. The response might contain the display name of the recipient of the share for general user experience improvement
+          description: >
+            Consumer successfully received the share. The response might contain
+            the display name of the recipient of the share for general
+            user experience improvement
           schema:
             type: object
             properties:
@@ -86,10 +87,8 @@ paths:
               description: >
                 Indication for the client when the service could be requested
                 again in HTTP Date format as used by the 
-
                 Internet Message Format [RFC5322] (e.g. `Wed, 21 Oct 2015
                 07:28:00 GMT`) or the number of seconds 
-
                 (e.g. 3000 if you the service is expected to be available again
                 within 50 minutes).
               type: string
@@ -110,7 +109,10 @@ paths:
             $ref: '#/definitions/NewNotification'
       responses:
         '201':
-          description: Receiver succesfully received the notification. The response body can contain a JSON object with some resonse data, depending on the specification of the actual notification.
+          description: >
+            Receiver succesfully received the notification. The response body
+            can contain a JSON object with some resonse data, depending on the
+            specification of the actual notification.
         '400':
           description: >
             Bad request due to invalid parameters, e.g. when `type` is invalid
@@ -139,16 +141,37 @@ paths:
             Retry-After:
               description: >
                 Indication for the client when the service could be requested
-                again in HTTP Date format as used by the 
-
-                Internet Message Format [RFC5322] (e.g. `Wed, 21 Oct 2015
-                07:28:00 GMT`) or the number of seconds 
-
-                (e.g. 3000 if you the service is expected to be available again
-                within 50 minutes).
+                again in HTTP Date format as used by the Internet Message Format
+                [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the number
+                of seconds (e.g. 3000 if you the service is expected to be
+                available again within 50 minutes).
               type: string
           schema:
             $ref: '#/definitions/Error'
+  /invite-accepted:
+    post:
+      summary: Inform the sender that the invitation was accepted to start sharing.
+      description: Inform about an accepted invitation so the user on the sender provider's side can initiate the OCM share creation.
+      parameters:
+        - name: invite
+          in: body
+          description: The JSON object to notify the OCM provider that an invite has been accepted.
+          required: true
+          schema:
+            $ref: "#/definitions/AcceptedInviteBody"
+      responses:
+        200:
+          description: Invitation accepted.
+          schema:
+            $ref: "#/definitions/AcceptedInviteResponse"
+        400:
+          description: The invitation token is invalid.
+          schema:
+            $ref: "#/definitions/Error" 
+        403:
+          description: Remote service is not trusted to accept invitations.
+          schema:
+            $ref: "#/definitions/Error"
 definitions:
   '400':
     type: object
@@ -167,10 +190,8 @@ definitions:
                   type: string
                   description: >
                     A validation error message which is understandable for both
-                    humans and machines (e.g. no use of 
-
-                    special characters) providing more information on the cause
-                    of the validation error.
+                    humans and machines (e.g. no use of special characters)
+                    providing more information on the cause of the validation error.
                   example: NOT_FOUND
   Error:
     type: object
@@ -181,10 +202,8 @@ definitions:
         type: string
         description: >
           An error message which is understandable for both humans and machines
-          (e.g. no use of 
-
-          special characters) providing more information on the cause of the
-          error.
+          (e.g. no use of special characters) providing more information
+          on the cause of the error.
         example: RESOURCE_NOT_FOUND
   NewShare:
     type: object
@@ -202,12 +221,9 @@ definitions:
         type: string
         description: >
           Consumer specific identifier of the user or group the provider wants
-          to share the resource with. 
-
-          This is known in advance. Please note that the consumer service
-          endpoint is known in advance as 
-
-          well, so this is no part of the request body.
+          to share the resource with. This is known in advance.
+          Please note that the consumer service endpoint is known in advance
+          as well, so this is no part of the request body.
         example: [email protected]
       name:
         type: string
@@ -233,12 +249,9 @@ definitions:
       sender:
         description: >
           Provider specific identifier of the user that wants to share the
-          resource. Please note that the 
-
-          requesting provider is being identified on a higher level, so the
-          former `remote` property 
-
-          is no part of the request body.
+          resource. Please note that the requesting provider is being
+          identified on a higher level, so the former `remote` property
+          is not part of the request body.
         type: string
         example: [email protected]
       ownerDisplayName:
@@ -259,41 +272,45 @@ definitions:
       resourceType:
         type: string
         description: |
-          Resource type (file, calendar, contact,...)
+          Resource type (file, calendar, contact, ...)
         example: file
       protocol:
         type: object
         description: >
-          The protocol which is used to establish synchronisation. At the moment
-          only `webdav` is 
-
-          supported, but other (custom) protocols might be added in the future.
+          The protocol(s) which is/are used to establish synchronisation.
         required:
           - name
           - options
         properties:
           name:
-            type: string
-            description: >
-              The name of the protocol which is used to establish
-              synchronisation. At the moment only `webdav` is 
-
-              supported, but other (custom) protocols might be added in the
-              future.
-            enum:
-              - webdav
-            example: webdav
+            type: array
+            items:
+              type: string
+              description: >
+                The name of the protocol(s) which is/are used to establish
+                synchronisation. The supported protocols are:
+                `webdav`, to access the data
+                `webapp`, to access remote web applications
+                Other custom protocols might be added in the future.
+              enum:
+                - webdav
+                - webapp
+              example: webdav
           options:
             type: object
             description: >
               JSON object with protocol specific options, e.g. `uri`,
-              `access_token`, `password`, `permissions` etc. At the moment
-
-              only `webdav` options are supported, but other (custom) protocol
-              options might be added in the future. For backward compatibility the webdav protocol will use the 'sharedSecret" as username and password
+              `access_token`, `password`, `permissions` etc.
+              For backward compatibility, the webdav protocol will use
+              `sharedSecret` as username and password.
+              The `webapp` protocol is expected to provide a (templated)
+              URI to a client-browsable view of the shared resource, with
+              all relevant applications enabled: implementations may
+              leverage the public link capability for this feature.
             example:
               sharedSecret: "hfiuhworzwnur98d3wjiwhr"
-              permissions: "{http://open-cloud-mesh.org/ns}share-permissions"
+              permissions: "{https://open-cloud-mesh.org/ns}share-permissions"
+              uriTemplate: "https://open-cloud-mesh.org/s/{path-to-shared-resources}"
   NewNotification:
     type: object
     required:
@@ -305,10 +322,8 @@ definitions:
         type: string
         description: >
           A notification type which is understandable for both humans and
-          machines (e.g. no use of 
-
-          special characters) providing more information on the cause of the
-          error.
+          machines (e.g. no use of special characters) providing more
+          information on the cause of the error.
         example: SHARE_ACCEPTED
       resourceType:
         type: string
@@ -326,3 +341,57 @@ definitions:
         example:
           message: "Recipient accepted the share"
           sharedSecret: "hfiuhworzwnur98d3wjiwhr"
+  AcceptedInvite:
+    type: object
+    allOf:
+      - properties:
+          token:
+            type: string
+            description: Token generated by the service sending the invitation.
+            example: xyz
+          senderProvider: 
+            type: string 
+            format: url
+            description: URL of the OCM sender service.
+            example: https://sender.org
+  AcceptedInviteBody:
+    type: object
+    allOf:
+      - properties:
+          recipientProvider:
+            type: string 
+            format: url
+            description: URL of the receiver OCM service.
+            example: https://receiver.org
+          token:
+            type: string
+            description: Token received in the invite
+            example: xyz
+          userID:
+            type: string
+            description: Unique ID to identify the user at the remote provider accepting the invite.
+            example: 9303
+          email:
+            type: string
+            description: Email ID of the user accepting the invite.
+            example: [email protected]
+          name:
+            type: string
+            description: Name of the user accepting the invite.
+            example: Richard Feynman
+  AcceptedInviteResponse:
+    type: object
+    allOf:
+      - properties:
+          userID:
+            type: string
+            description: Unique ID to identify the sender at the local provider.
+            example: 9302
+          email:
+            type: string
+            description: Email ID of the user that sent the invite.
+            example: [email protected]
+          name:
+            type: string
+            description: Name of the user that sent the invite.
+            example: John Doe