-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdrs-api.yml
452 lines (440 loc) · 16.4 KB
/
drs-api.yml
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
swagger: "2.0"
info:
description: "An aspirationally DRS interface to the HCA DSS."
title: "DRS Serverless"
version: "1.0.0"
host: test
schemes:
- https
basePath: /v1
produces:
- application/json
paths:
/files/{uuid}:
head:
operationId: drs.api.files.head
summary: Retrieve a file's metadata given an UUID and optionally a version.
description: >
Given a file UUID, return the metadata for the latest version of that file. If the version is provided, that
version's metadata is returned instead. The metadata is returned in the headers.
parameters:
- name: uuid
in: path
description: A RFC4122-compliant ID for the file.
required: true
type: string
- name: version
in: query
description: Timestamp of file creation in DSS_VERSION format. If this is not provided, the latest version is returned.
required: false
type: string
responses:
200:
description: Returns metadata
headers:
# edits to here should probably be reflected in the 302 section immediately below.
X-DSS-CREATOR-UID:
description: User ID who created this file.
type: integer
format: int64
X-DSS-VERSION:
description: Timestamp of file creation in DSS_VERSION format.
type: string
X-DSS-CONTENT-TYPE:
description: Content-type of the file.
type: string
X-DSS-SIZE:
description: File size (bytes).
type: integer
format: int64
X-DSS-CRC32C:
description: CRC-32C (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{8}$"
X-DSS-S3-ETAG:
description: S3 ETag (in hex format) of the file contents.
type: string
pattern: "^[a-z0-9]{32}(-([2-9]|[1-8][0-9]|9[0-9]|[1-8][0-9]{2}|9[0-8][0-9]|99[0-9]|[1-8][0-9]{3}|9[0-8][0-9]{2}|99[0-8][0-9]|999[0-9]|10000))?$"
X-DSS-SHA1:
description: SHA-1 (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{40}$"
X-DSS-SHA256:
description: SHA-256 (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{64}$"
500:
$ref: '#/responses/ServerError'
502:
$ref: '#/responses/BadGateway'
503:
$ref: '#/responses/ServiceUnavailable'
504:
$ref: '#/responses/GatewayTimeout'
get:
operationId: drs.api.files.get
summary: Retrieve a file given a UUID and optionally a version.
description: >
Given a file UUID, return the latest version of that file. If the version is provided, that version of the file
is returned instead.
Headers will contain the data store metadata for the file.
This endpoint returns a HTTP redirect to another HTTP endpoint with the file contents.
parameters:
- name: uuid
in: path
description: A RFC4122-compliant ID for the file.
required: true
type: string
pattern: "[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}"
- name: version
in: query
description: Timestamp of file creation in DSS_VERSION format. If this is not provided, the latest version is returned.
required: false
type: string
responses:
301:
description: >
The file is still being fetched. The request is being handled asynchronously. The client should follow the
redirect after the delay specified in the Retry-After header.
headers:
Retry-After:
description: Delay in seconds. The client should follow the redirect after waiting for this duration.
type: integer
format: int64
302:
description: Redirects to a signed URL with the data.
headers:
# edits to here should probably be reflected in the 200 section above.
X-DSS-CREATOR-UID:
description: User ID who created this file.
type: integer
format: int64
X-DSS-VERSION:
description: Timestamp of file creation in DSS_VERSION format.
type: string
format: DSS_VERSION
X-DSS-CONTENT-TYPE:
description: Content-type of the file.
type: string
X-DSS-SIZE:
description: File size (bytes).
type: integer
format: int64
X-DSS-CRC32C:
description: CRC-32C (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{8}$"
X-DSS-S3-ETAG:
description: S3 ETag (in hex format) of the file contents.
type: string
pattern: "^[a-z0-9]{32}(-([2-9]|[1-8][0-9]|9[0-9]|[1-8][0-9]{2}|9[0-8][0-9]|99[0-9]|[1-8][0-9]{3}|9[0-8][0-9]{2}|99[0-8][0-9]|999[0-9]|10000))?$"
X-DSS-SHA1:
description: SHA-1 (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{40}$"
X-DSS-SHA256:
description: SHA-256 (in hex format) of the file contents in hex.
type: string
pattern: "^[a-z0-9]{64}$"
400:
description: Bad request
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: >
Machine-readable error code. The types of return values should not be changed lightly.
The code `illegal_token` is returned when the token parameter cannot be understood.
enum: [illegal_token]
required:
- code
500:
$ref: '#/responses/ServerError'
502:
$ref: '#/responses/BadGateway'
503:
$ref: '#/responses/ServiceUnavailable'
504:
$ref: '#/responses/GatewayTimeout'
default:
description: Unexpected error
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: Machine-readable error code. The types of return values should not be changed lightly.
enum: [unhandled_exception, illegal_arguments, not_found]
required:
- code
put:
operationId: drs.api.files.put
summary: Create a new version of a file
description: >
Create a new version of a file with a given UUID. The contents of the file are provided by the client by
reference using a cloud object storage URL. The file on the cloud object storage service must have metadata set
listing the file checksums and content-type.
The metadata fields required are:
- hca-dss-sha256: SHA-256 checksum of the file
- hca-dss-sha1: SHA-1 checksum of the file
- hca-dss-s3_etag: S3 ETAG checksum of the file. See
https://stackoverflow.com/questions/12186993/what-is-the-algorithm-to-compute-the-amazon-s3-etag-for-a-file-larger-than-5gb
for the general algorithm for how checksum is calculated. For files smaller than 64MB, this is the MD5 checksum
of the file. For files larger than 64MB but smaller than 640,000MB, we use 64MB chunks. For files larger than
640,000MB, we use a chunk size equal to the total file size divided by 10000, rounded up to the nearest MB.
MB, in this section, refers to 1,048,576 bytes. Note that 640,000MB is not the same as 640GB!
- hca-dss-crc32c: CRC-32C checksum of the file
parameters:
- name: uuid
in: path
description: A RFC4122-compliant ID for the file.
required: true
type: string
pattern: "[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}"
- name: version
in: query
description: Timestamp of file creation in DSS_VERSION format. If this is not provided, the latest version is returned.
required: true
type: string
format: DSS_VERSION
- name: json_request_body
in: body
required: true
schema:
type: object
properties:
source_url:
description: Cloud bucket URL for source data. Example is "s3://bucket_name/serious_dna.fa" .
type: string
pattern: "^(gs|s3|wasb)://"
creator_uid:
description: User ID who is creating this file.
type: integer
format: int64
required:
- source_url
- creator_uid
responses:
200:
description: Returned when the file is already present and is identical to the file being uploaded.
schema:
type: object
properties:
version:
description: Timestamp of file creation in DSS_VERSION format.
type: string
format: DSS_VERSION
required:
- version
201:
description: Returned when the file is successfully copied.
schema:
type: object
properties:
version:
description: Timestamp of file creation in DSS_VERSION format.
type: string
format: DSS_VERSION
required:
- version
400:
description: Returned when the server could not process the request. Examine the code for more details.
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: >
Machine-readable error code. The types of return values should not be changed lightly.
The code `unknown_source_schema` is returned when the source_url of the file has an unsupported
schema.
The code `illegal_version` is returned when version is not a DSS_VERSION format-compliant timestamp.
enum: [unknown_source_schema, illegal_version]
required:
- code
409:
description: Returned when a file with the same UUID and version already exists
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: Machine-readable error code. The types of return values should not be changed lightly.
enum: [file_already_exists]
required:
- code
422:
description: Returned when a request cannot be processed due to invalid values in a supplied entity.
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: Machine-readable error code. The types of return values should not be changed lightly.
The code `missing_checksum` is returned when the file uploaded is missing a required checksum.
enum: [missing_checksum]
required:
- code
500:
$ref: '#/responses/ServerError'
502:
$ref: '#/responses/BadGateway'
503:
$ref: '#/responses/ServiceUnavailable'
504:
$ref: '#/responses/GatewayTimeout'
default:
description: Unexpected error
schema:
allOf:
- $ref: '#/definitions/Error'
- type: object
properties:
code:
type: string
description: Machine-readable error code. The types of return values should not be changed lightly.
enum: [unhandled_exception, Forbidden, Unauthorized, illegal_arguments, read_only]
required:
- code
definitions:
File:
type: object
properties:
uuid:
type: string
description: File unique ID
pattern: "[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}"
name:
type: string
description: Filename (unique within a bundle)
versions:
type: array
description: List of versions
items:
type: string
required:
- uuid
- name
- versions
file_version:
type: object
description: Object describing a single file in the files list of a bundle.
properties:
name:
type: string
description: Filename (unique within a bundle)
content-type:
type: string
description: Content-type of the file.
indexed:
type: boolean
description: True if this file is to be indexed.
url:
description: Direct access or presigned URL, if requested.
type: string
uuid:
type: string
description: A RFC4122-compliant ID for the file.
pattern: "[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}"
version:
type: string
format: DSS_VERSION
description: Timestamp of bundle creation in DSS_VERSION format.
size:
type: integer
format: int64
description: File size (bytes).
crc32c:
type: string
description: CRC-32C (in hex format) of the file contents in hex.
pattern: "^[a-z0-9]{8}$"
s3_etag:
type: string
description: S3 ETag (in hex format) of the file contents.
pattern: "^[a-z0-9]{32}(-([2-9]|[1-8][0-9]|9[0-9]|[1-8][0-9]{2}|9[0-8][0-9]|99[0-9]|[1-8][0-9]{3}|9[0-8][0-9]{2}|99[0-8][0-9]|999[0-9]|10000))?$"
sha1:
type: string
description: SHA-1 (in hex format) of the file contents in hex.
pattern: "^[a-z0-9]{40}$"
sha256:
type: string
description: SHA-256 (in hex format) of the file contents in hex.
pattern: "^[a-z0-9]{64}$"
required:
- name
- content-type
- indexed
- uuid
- version
- size
- crc32c
- s3_etag
- sha1
- sha256
Error:
type: object
properties:
status:
type: integer
format: int32
description: HTTP error code.
code:
type: string
description: >
Machine-readable error code. The types of return values should not be changed lightly. Individual endpoints
should list an enumeration of possible return codes. All endpoints should expect the possibility of the
return code `unhandled_exception` and `illegal_arguments`.
title:
type: string
description: Human-readable error code.
stacktrace:
type: string
description: Exception stacktrace, if any.
required:
# once we fix up all the existing endpoints, we can add 'code' to the set of required fields.
- title
FilesGetResponse:
type: object
properties:
files:
type: string
responses:
ServerError:
description: Server Error.
headers:
Retry-After:
description: Delay in seconds, service clients should retry after the delay.
type: integer
format: int64
BadGateway:
description: Bad Gateway.
headers:
Retry-After:
description: Delay in seconds, service clients should retry after the delay.
type: integer
format: int64
ServiceUnavailable:
description: Service Unavailable.
headers:
Retry-After:
description: Delay in seconds, service clients should retry after the delay.
type: integer
format: int64
GatewayTimeout:
description: Gateway Timeout.
headers:
Retry-After:
description: Delay in seconds, service clients should retry after the delay.
type: integer
format: int64