Invitation workflow for OCM, take 2

spec.yaml

@@ -37,7 +37,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:
@@ -86,10 +85,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
@@ -140,15 +137,54 @@ 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
           schema:
             $ref: '#/definitions/Error'
+  /invites/forward:
+    post:
+      summary: Forward an invitation to start sharing
+      description: Forwards an invitation received through an out-of-band channel, email for example.
+      parameters:
+        - name: invite
+          in: body
+          description: The JSON object representing an invitation to send to an end-user.
+          required: true
+          schema:
+            $ref: "#/definitions/ForwardInviteBody"
+      responses:
+        200:
+          description: Invitation forwarded.
+        400:
+          description: |
+            Bad request due to invalid parameters, e.g. provider is not valid.
+          schema:
+            $ref: "#/definitions/400"            
+  /invites/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.
+        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
@@ -259,7 +295,9 @@ definitions:
       resourceType:
         type: string
         description: |
-          Resource type (file, calendar, contact,...)
+          Resource type (file, webapp, calendar, contact, ...). A `webapp` share
+          is an application that can be opened on the remote end, typically
+          to enable collaborative workflows.
         example: file
       protocol:
         type: object
@@ -277,7 +315,6 @@ definitions:
             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:
@@ -305,10 +342,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 +361,41 @@ 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