-
Notifications
You must be signed in to change notification settings - Fork 9
/
spec.yaml
646 lines (644 loc) · 25.4 KB
/
spec.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
swagger: "2.0"
info:
title: Open Cloud Mesh API
description: Open Cloud Mesh Open API Specification.
version: 1.1.0
x-logo:
url: logo.png
schemes:
- https
consumes:
- application/json
produces:
- application/hal+json
parameters:
id:
name: id
in: path
description: Unique ID to identify the share at the consumer side.
required: true
type: string
page:
name: page
in: query
type: integer
required: false
default: 1
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:
/ocm-provider:
get:
summary: Discovery endpoint
description: >
This endpoint returns a number of properties used to discover the capabilities
offered by a remote cloud storage. The endpoint is named `/ocm-provider` owing
to already established practices and constraints with the main cloud storages
that implement OCM (see https://github.com/cs3org/OCM-API/pull/37#issuecomment-435875108
for more details).
responses:
"200":
description: The capabilities of this OCM service
schema:
$ref: "#/definitions/Discovery"
/shares:
post:
summary: Create a new share
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:
- name: share
in: body
description: The JSON object to create a new share at the consumer side.
required: true
schema:
$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.
schema:
type: object
properties:
recipientDisplayName:
type: string
description: display name of the recipient
example: John Doe
"400":
description: >
Bad request due to invalid parameters, e.g. when `shareWith` is not
found or required properties are missing.
schema:
$ref: "#/definitions/400"
"401":
description: Client cannot be authenticated as a trusted service.
schema:
$ref: "#/definitions/Error"
"403":
description: Trusted service is not authorized to create shares.
schema:
$ref: "#/definitions/Error"
"501":
description: >-
The consumer doesn't support incoming external shares, the share
type or the resource type is not supported.
schema:
$ref: "#/definitions/Error"
"503":
description: >-
The consumer is temporary unavailable (e.g. due to planned
maintenance).
headers:
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).
type: string
schema:
$ref: "#/definitions/Error"
/mfa-capable:
get:
summary: Inform the sender that the provider will enforce MFA requirements.
description: >
Signal that this OCM provider has the capability to enforce MFA when accessing
remote shares.
A sender MAY set the permission `mfa-enforced` on a share to this provider:
when a consumer attempts to access such a share, the consumer server SHOULD
enforce, prior to access, that a session exists for the consumer and that
it has been authenticated with MFA, or prompt the consumer in order to
elevate their session to MFA if that is applicable.
Note: there is no guarantee that the consumer service actually enforces any MFA
requirements, so a trust must be established before relying on this capability.
responses:
"200":
description: |
The provider claims that it is capable of enforcing MFA requirements.
"404":
description: |
The provider does not have the capability to enforce MFA requirements.
/notifications:
post:
summary: Send a notification to a remote party about a previously known entity
description: |
Notifications are optional messages. They are expected to be used to inform the
other party about a change about a previously known entity, such as a share or
a trusted user.
For example, a notification MAY be sent by a recipient to let the provider know
that the recipient declined a share. In this case, the provider site MAY mark the
share as declined for its user(s).
Similarly, it MAY be sent by a provider to let the recipient know that the provider
removed a given share, such that the recipient MAY clean it up from its database.
A notification MAY also be sent to let a recipient know that the provider
removed that recipient from the list of trusted users, along with any related share.
The recipient MAY reciprocally remove that provider from the list of trusted users,
along with any related share.
parameters:
- name: notification
in: body
description: The JSON object with a new notification
required: true
schema:
$ref: "#/definitions/NewNotification"
responses:
"201":
description: |
Receiver succesfully received the notification. The response body MAY contain
a JSON object with some resonse data, depending on the actual notification.
"400":
description: |
Bad request due to invalid parameters, e.g. when `type` is invalid
or missing.
schema:
$ref: "#/definitions/400"
"401":
description: Client cannot be authenticated as a trusted service.
schema:
$ref: "#/definitions/Error"
"403":
description: Trusted service is not authorized to create notifications.
schema:
$ref: "#/definitions/Error"
"501":
description: |
The receiver doesn't support notifications, the resource type is not
supported.
schema:
$ref: "#/definitions/Error"
"503":
description: |
The receiver is temporary unavailable (e.g. due to planned
maintenance).
headers:
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).
type: string
schema:
$ref: "#/definitions/Error"
/invite-accepted:
post:
summary: Inform the sender that an 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.
To protect the identity of the parties, for shares created following an OCM invitation,
the user id MAY be hashed, and recipients implementing the OCM invitation workflow
MAY refuse to process shares coming from unknown parties.
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"
404:
description: The invitation token does not exist.
schema:
$ref: "#/definitions/Error"
409:
description: User is already known by the OCM provider.
schema:
$ref: "#/definitions/Error"
definitions:
"400":
type: object
allOf:
- $ref: "#/definitions/Error"
- properties:
validationErrors:
type: array
items:
type: object
properties:
name:
type: string
example: shareWith
message:
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.
example: NOT_FOUND
Error:
type: object
required:
- message
properties:
message:
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.
example: RESOURCE_NOT_FOUND
Discovery:
type: object
required:
- enabled
- apiVersion
- endPoint
- resourceTypes
properties:
enabled:
type: boolean
description: Whether the OCM service is enabled at this endpoint
apiVersion:
type: string
description: The OCM API version this endpoint supports
example: 1.1.0
endPoint:
type: string
description: The URI of the OCM API available at this endpoint
example: https://my-cloud-storage.org/ocm
provider:
type: string
description: A friendly branding name of this endpoint
example: MyCloudStorage
resourceTypes:
type: array
description: |
A list of all supported resource types with their access protocols.
Each resource type is identified by its `name`: the list MUST NOT
contain more than one resource type object per given `name`.
items:
type: object
properties:
name:
type: string
description: |
A supported resource type (file, folder, calendar, contact, ...).
Implementations MUST support `file` at a minimum.
example: file
shareTypes:
type: array
description: |
The supported recipient share types.
Implementations MUST support `user` at a minimum.
items:
type: string
enum: ["user", "group", "federation"]
example: ["user"]
protocols:
type: object
description: |
The supported protocols to access shares at this endpoint.
Implementations MUST support `webdav` at a minimum.
properties:
webdav:
type: string
description: |
The top-level WebDAV path at this endpoint. In order to access
a remote shared resource, implementations MAY use this path
as a prefix, or as the full path (see sharing examples).
example: /remote/dav/ocm/
webapp:
type: string
description: |
The top-level path for web apps at this endpoint. This value
is provided for documentation purposes, and it SHALL NOT
be intended as a prefix for share requests.
example: /app/ocm/
datatx:
type: string
description: |
The top-level path to be used for data transfers. This
value is provided for documentation purposes, and it SHALL
NOT be intended as a prefix. In addition, implementations
are expected to execute the transfer using WebDAV as
the wire protocol.
example: /remote/dav/ocm/
capabilities:
type: array
description: |
The optional capabilities exposed at this endpoint according to the present
specifications. As implementations MUST provide `/shares` to be compliant,
it is not necessary to expose it as a capability.
items:
type: string
enum: ["/notifications", "/invite-accepted", "/mfa-capable"]
example:
["/invite-accepted"]
NewShare:
type: object
required:
- shareWith
- name
- providerId
- owner
- sender
- protocol
- permission
- shareType
- resourceType
properties:
shareWith:
type: string
description: |
Consumer specific identifier of the user, group or federation 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.
example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org
name:
type: string
description: Name of the resource (file or folder).
example: resource.txt
description:
type: string
description: Optional description of the resource (file or folder).
example: |
This is the Open API Specification file (in YAML format) of the Open
Cloud Mesh API.
providerId:
type: string
description: |
Identifier to identify the shared resource at the provider side. This is
unique per provider such that if the same resource is shared twice,
this providerId will not be repeated.
example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
owner:
description: |
Provider specific identifier of the user who owns the resource.
type: string
example: 6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl
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 not part of the request body.
type: string
example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl
ownerDisplayName:
type: string
description: |
Display name of the owner of the resource
example: Dimitri
senderDisplayName:
type: string
description: |
Display name of the user that wants to share the resource
example: John Doe
shareType:
type: string
enum: ["user", "group", "federation"]
description: |
Recipient share type
example: user
resourceType:
type: string
description: |
Resource type (file, folder, calendar, contact, ...)
example: file
expiration:
type: integer
description: |
The expiration time for the OCM share, in seconds
of UTC time since Unix epoch. If omitted, it is assumed
that the share does not expire.
protocol:
type: object
description: |
JSON object with specific options for each protocol.
The supported protocols are:
- `webdav`, to access the data
- `webapp`, to access remote web applications
- `datatx`, to transfer the data to the remote endpoint
Other custom protocols might be added in the future.
additionalProperties:
type: object
required:
- name
properties:
name:
type: string
description: |
The name of the protocol. If `multi` is given, one or more protocol
endpoints are expected to be defined according to the optional
properties specified below.
Otherwise, at least `webdav` is expected to be supported, and
its options MAY be given in the opaque `options` payload for
compatibility with v1.0 implementations (see examples).
CAREFUL: client implementers should be aware that v1.1 servers
MAY support both `webdav` and `multi`, but v1.0 servers MAY
only support `webdav`.
options:
type: object
description: |
This property is now deprecated. Implementations are encouraged to
transition to the new optional properties defined below, such that
this field may be removed in a future major version of the spec.
webdav:
type: object
properties:
sharedSecret:
type: string
description: |
An optional secret to be used to access the resource,
such as a bearer token.
permissions:
type: array
items:
type: string
description: |
The permissions granted to the sharee.
- `read` allows read-only access including download of a copy.
- `write` allows create, update, and delete rights on the resource.
- `share` allows re-share rights on the resource.
- `mfa-enforced` requires the user accessing the resource to be
MFA-authenticated. This permission MAY be used if the
provider exposes the `mfa-capable` capability.
enum: ["read", "write", "share", "mfa-enforced"]
uri:
type: string
description: |
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/ocm-provider` endpoint MUST
be used, or it may be absolute (recommended). Additionally, the URI
MAY include a secret hash in the path, in which case there MAY be
no associated `sharedSecret`.
webapp:
type: object
properties:
uriTemplate:
type: string
description: |
A templated URI to a client-browsable view of the shared resource,
such that users may use the web applications available at the site.
The URI MAY include a secret hash in the path. If the path includes
a `{relative-path-to-shared-resource}` placeholder, implementations
MAY replace it with the actual path to ease user interaction.
viewMode:
type: string
description: |
The permissions granted to the sharee.
- `view` allows access to the web app in view-only mode.
- `read` allows read and download access via the web app.
- `write` allows full editing rights via the web app.
- `mfa-enforced` requires the user accessing the resource to be
MFA-authenticated. This permission MAY be used if the
provider exposes the `mfa-capable` capability.
enum: ["view", "read", "write", "mfa-enforced"]
sharedSecret:
type: string
description: |
An optional secret to be used to access the remote web app,
for example in the form of a bearer token.
datatx:
type: object
properties:
sharedSecret:
type: string
description: |
An optional secret to be used to access the resource,
for example in the form of a bearer token.
srcUri:
type: string
description: |
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/ocm-provider` endpoint MUST
be used, or it may be absolute (recommended). Additionally, the
URI MAY include a secret hash in the path.
size:
type: integer
example:
singleProtocolLegacy:
name: "webdav"
options:
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
permissions: "some permissions scheme"
singleProtocolNew:
name: "webdav"
options:
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
webdav:
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
permissions: ["read", "write"]
uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
multipleProtocols:
name: "multi"
options:
webdav:
permissions: ["read", "mfa-enforced"]
uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
webapp:
uriTemplate: "https://open-cloud-mesh.org/app/ocm/hfiuhworzwnur98d3wjiwhr/{relative-path-to-shared-resource}"
viewMode: "read"
datatx:
srcUri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
size: 100000
NewNotification:
type: object
required:
- notificationType
- resourceType
- providerId
properties:
notificationType:
type: string
description: |
A notification type that is understandable for both humans and
machines (e.g. no use of special characters) providing more
information on the cause of the error.
Values that MAY be used by implementations are:
`SHARE_ACCEPTED`, `SHARE_DECLINED`, `REQUEST_RESHARE`,
`SHARE_UNSHARED`, `RESHARE_UNDO`, `RESHARE_CHANGE_PERMISSION`,
`USER_REMOVED`.
resourceType:
type: string
description: |
Resource type (file, folder, user, calendar, contact, ...)
providerId:
type: string
description: |
Identifier of the shared resource. If the resourceType is `file`,
then see `NewShare/providerId` for the required information.
If the resourceType is `user`, then this is the user identifier
previously sent via `/invite-accepted`.
notification:
type: object
description: |
Optional additional parameters, depending on the notification
and the resource type.
example:
shareWasAccepted:
notificationType: "SHARE_ACCEPTED"
resourceType: "file"
providerId: "7c084226-d9a1-11e6-bf26-cec0c932ce01"
notification:
message: "Recipient accepted the share"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
userWasRemoved:
notificationType: "USER_REMOVED"
resourceType: "user"
providerId: "51dc30ddc473d43a6011e9ebba6ca770"
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: 51dc30ddc473d43a6011e9ebba6ca770
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