forked from cs3org/OCM-API
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathspec.yaml
328 lines (312 loc) · 10.6 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
swagger: '2.0'
info:
title: Open Cloud Mesh API
description: Open Cloud Mesh Open API Specification.
version: 1.0.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:
/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'
/notifications:
post:
summary: Send a notification to a trusted service
description: >-
Should be used to be 'polite', e.g. to let the provider know that a user
has removed the 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 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
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'
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
NewShare:
type: object
required:
- shareWith
- name
- providerId
- owner
- protocol
- permission
- shareType
- resourceType
properties:
shareWith:
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.
example: [email protected]
name:
type: string
description: Name of the resource (file or folder).
example: spec.yaml
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 resource at the provider side. This is
unique per provider.
example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
owner:
description: |
Provider specific identifier of the user who owns the resource.
type: string
example: [email protected]
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.
type: string
example: [email protected]
ownerDisplayName:
type: string
description: |
Display name of the owner of the resource
example: Dimitri
senderDisplayName:
type: string
description: |
Display name of the owner of the resource
example: John Doe
shareType:
type: string
description: |
Share type (user or group share)
example: user
resourceType:
type: string
description: |
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.
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
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
example:
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
permissions: "{http://open-cloud-mesh.org/ns}share-permissions"
NewNotification:
type: object
required:
- notificationType
- resourceType
- message
properties:
notificationType:
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.
example: SHARE_ACCEPTED
resourceType:
type: string
description: |
A resource type (e.g. file, calendar, contact)
example: file
providerId:
type: string
description: ID of the resource on the provider side
example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
notification:
type: object
description: >
optional additional parameters, depending on the notification and the resource type
example:
message: "Recipient accepted the share"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"