diff --git a/spec.yaml b/spec.yaml index 166fe31..135d434 100644 --- a/spec.yaml +++ b/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/AcceptedInvite" + 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: peter.szegedi@geant.org 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: john@apiwise.nl 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,44 @@ definitions: example: message: "Recipient accepted the share" sharedSecret: "hfiuhworzwnur98d3wjiwhr" + AcceptedInvite: + 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: richard@receiver.org + 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: john@sender.org + name: + type: string + description: Name of the user that sent the invite. + example: John Doe