forked from quetz-al/quetzal
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenapi.yaml
1279 lines (1217 loc) · 39.4 KB
/
openapi.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
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
openapi: 3.0.2
info:
title: Quetzal API
version: "{{ version }}"
description: |
Quetzal (short for Quetzalcóatl, the feathered snake), a RESTful API designed
to store data files and manage their associated metadata.
Please read the Quetzal documentation at
[readthedocs.org](https://quetzal-api.readthedocs.org)
for more details on the features and use-cases of this API. To understand
the endpoints presented in this API, read the
[concepts](https://quetzal-api.readthedocs.io/en/latest/design.html#concepts)
and other design elements defined for Quetzal.
# Authentication
All API operations require a either a bearer token authentication header, or
an API key header. There is one exception for the endpoint to create a new
bearer token, which is only accessible with a basic HTTP authentication.
Read the [OpenAPI specification authentication section](https://swagger.io/docs/specification/authentication/)
for more details.
# Errors
Quetzal uses standard HTTP error codes to indicate success or failure of its
operations. The body of the response follows
[RFC-7807](https://tools.ietf.org/html/rfc7807) to provide details on an
error. For example:
```
{
"type": "https://quetz.al/problems/some-name",
"title": "Bad request.",
"status": 400,
"detail": "Incorrect foo due to missing bar.",
"instance": "/some_path/some_id"
}
```
# Versioning
API version | Changes
------------|---------
0.5.0 | [API changes](https://github.com/quetz-al/quetzal/releases/tag/v0.5.0)
0.4.0 | [API changes](https://github.com/quetz-al/quetzal/releases/tag/v0.4.0)
0.3.0 | [API changes](https://github.com/quetz-al/quetzal/releases/tag/v0.3.0)
0.2.0 | [API changes](https://github.com/quetz-al/quetzal/releases/tag/v0.2.0)
0.1.0 | [API changes](https://github.com/quetz-al/quetzal/releases/tag/v0.1.0)
# Notes
* Add file delete mechanism is not fully tested yet. It should clean files
when the workspace is committed, but there are no unit test to verify this.
* Workspace update through a PUT is not available yet.
* Workspace commit is still very naive and could be improved.
# API Reference
The following documentation is auto-generated from the OpenAPI v3
specification by redoc.
termsOfService: "https://{{ server }}/terms" # TODO: activate this URL
contact:
name: API support
url: https://quetz.al
email: [email protected]
license:
name: BSD-3-Clause
url: https://opensource.org/licenses/BSD-3-Clause
x-logo:
url: "https://{{ server }}/static/logo_h.png"
altText: Quetzal logo
servers:
- url: https://api.quetz.al/api/v1
description: Public server
- url: https://stage.quetz.al/api/v1
description: Staging server
- url: https://local.quetz.al/api/v1
description: Local development data server
externalDocs:
url: https://quetzal-api.readthedocs.org
description: Quetzal documentation at readthedocs.org.
paths:
# Authentication endpoints
/auth/token:
post:
summary: Login.
description: |-
Authenticate with simple HTTP authentication and obtain a bearer token.
This bearer token can be used on the other endpoints of the API.
tags:
- authentication
operationId: auth.get_token
x-openapi-router-controller: quetzal.app.api.router
security:
- basic: []
responses:
'200':
$ref: '#/components/responses/AuthenticationSuccess'
default:
$ref: '#/components/responses/Error'
/auth/logout:
post:
summary: Logout.
description: |-
Logout by invalidating the existing token.
tags:
- authentication
operationId: auth.logout
x-openapi-router-controller: quetzal.app.api.router
security:
- bearer: []
responses:
'204':
description: Logout successful
default:
$ref: '#/components/responses/Error'
# Data endpoints (workspaces)
/data/workspaces/:
get:
summary: List workspaces.
description: |-
List workspace details. Optionally, filter workspaces according to
their name, owner or whether they have been deleted.
tags:
- data
- public
- workspace
operationId: workspace.fetch
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
- name: name
in: query
description: Filter workspaces by name
required: false
schema:
type: string
- name: owner
in: query
description: Filter workspaces by owner
required: false
schema:
type: string
- name: deleted
in: query
description: Include deleted workspaces
schema:
type: boolean
responses:
'200':
$ref: '#/components/responses/PaginatedWorkspaces'
default:
$ref: '#/components/responses/Error'
post:
summary: Create workspace.
description: |-
Create a workspace, which initializes the basic resources and
information associated with it, and then schedules some background
tasks to initialize Cloud resources.
tags:
- data
- public
operationId: workspace.create
x-openapi-router-controller: quetzal.app.api.router
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
required: true
responses:
'201':
$ref: '#/components/responses/WorkspaceDetails'
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}:
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
get:
summary: Workspace details.
description: |-
Obtain all information of a workspace.
tags:
- data
- workspace
operationId: workspace.details
x-openapi-router-controller: quetzal.app.api.router
responses:
'200':
$ref: '#/components/responses/WorkspaceDetails'
default:
$ref: '#/components/responses/Error'
delete:
summary: Delete workspace.
description: |-
Marks a workspace for deletion.
Workspaces cannot be immediately deleted, due to complex resource
management. Moreover, workspaces are not completely deleted in order to
keep a history of workspaces and possibly to add some resurrect
functionality. Instead, all of their resources are freed and its
status is marked as DELETED.
The current status of the workspace can be requested on this same path,
using a GET instead of a DELETE.
tags:
- data
operationId: workspace.delete
x-openapi-router-controller: quetzal.app.api.router
responses:
'202':
description: Workspace marked for deletion
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/commit:
put:
summary: Commit workspace.
description: |-
Requests a workspace commit. That is, all metadata added or modified
in this workspace will be moved to the global, public workspace,
becoming available to all users. Metadata versions will be incremented.
tags:
- data
- workspace
operationId: workspace.commit
x-openapi-router-controller: quetzal.app.api.router
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
responses:
'202':
$ref: '#/components/responses/WorkspaceDetails'
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/scan:
put:
summary: Update views.
description: |-
Requests the update of the views of a workspace. All the internal
databases used for the query operation will be updated to contain the
latest modifications of the metadata.
tags:
- data
- workspace
operationId: workspace.scan
x-openapi-router-controller: quetzal.app.api.router
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
responses:
'202':
$ref: '#/components/responses/WorkspaceDetails'
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/files/:
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
get:
summary: List files.
description: |-
Fetches all the files that have been added in this workspace. Files
whose metadata has been modified in this workspace will also be
included.
The file details included in the response only show their base metadata.
tags:
- data
- workspace
operationId: workspace_file.fetch
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/fileFilter'
responses:
'200':
$ref: '#/components/responses/PaginatedFiles'
default:
$ref: '#/components/responses/Error'
post:
summary: Upload file.
description: |-
Upload a new file to a workspace by sending its contents.
The file will not have any additional metadata associated to it.
tags:
- data
- workspace
operationId: workspace_file.create
x-openapi-router-controller: quetzal.app.api.router
parameters:
- name: path
in: query
description: |-
Path for the filename that will be set on the base metadata.
This parameter is provided as a workaround to the fact that files
are usually uploaded without their complete path on the filename
field of the form-data request.
required: false
schema:
type: string
example: study/s001
- name: temporary
in: query
description: True when the uploaded file is a temporary file.
required: false
schema:
type: boolean
example: false
requestBody:
content:
# There are some limitations of the wsgi server and connexion that
# do not let us have a correct complex multipart
multipart/form-data:
schema:
'$ref': '#/components/schemas/FileContents'
responses:
'201':
$ref: '#/components/responses/FileDetails'
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/files/{uuid}:
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
- name: uuid
in: path
description: File identifier
required: true
schema:
type: string
format: uuid
get:
summary: Fetch file.
description: |-
Serves the file contents or its metadata, according to the accepted
content response header. When the metadata is requested, this returns
the updated version with the modifications that may have been
introduced in this workspace.
tags:
- data
- workspace
operationId: workspace_file.details
x-openapi-router-controller: quetzal.app.api.router
responses:
'200':
$ref: '#/components/responses/FileContentsOrMetadata'
default:
$ref: '#/components/responses/Error'
patch:
summary: Modify metadata.
description: |-
Change the file metadata by updating it. Updating metadata changes
key/value pairs, adding a new key/value pair if does not exist and
changing the value if the key already exists. However, it cannot delete
a key/value that already exists. To delete metadata, refer to the
PUT method on this endpoint.
tags:
- data
- workspace
operationId: workspace_file.update_metadata
x-openapi-router-controller: quetzal.app.api.router
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataByFamily'
responses:
'200':
$ref: '#/components/responses/FileMetadata'
default:
$ref: '#/components/responses/Error'
put:
summary: Rewrite metadata.
description: |-
Change the file metadata entirely. In contrast to the PATCH method to
on this endpoint, this method sets the new metadata and discards any
previous metadata that was defined before.
tags:
- data
- workspace
operationId: workspace_file.set_metadata
x-openapi-router-controller: quetzal.app.api.router
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataByFamily'
responses:
'200':
$ref: '#/components/responses/FileMetadata'
default:
$ref: '#/components/responses/Error'
delete:
summary: Delete a file.
description: |-
Marks a file for deletion. File deletion will only occur when the
workspace is committed. This operation will set the base metadata
"state" to "deleted". Note that, in order to delete a file, the
workspace must have access to all the families related to the file.
In other words, if a file has metadata on families `base`, `foo` and
`bar`, then the workspace of this operation must have these three
families. Otherwise, this operation returns an error.
tags:
- data
- workspace
operationId: workspace_file.delete
x-openapi-router-controller: quetzal.app.api.router
responses:
'202':
description: File marked for deletion.
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/queries/:
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
get:
summary: List queries.
description: |-
List all the queries that are associated with a workspace.
Note that each query listed here is shown _without_ its results, for
brevity.
tags:
- data
- workspace
- query
operationId: workspace_query.fetch
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
$ref: '#/components/responses/PaginatedQueries'
default:
$ref: '#/components/responses/Error'
post:
summary: Prepare a query.
description: |-
Queries in Quetzal are saved as a resource associated to a workspace.
This endpoint creates one and responds with a *see other* status
referencing the query details endpoint.
Since the query details contains the query results as a
paginated list, this endpoint also accepts the normal pagination
parameters.
tags:
- data
- workspace
- query
operationId: workspace_query.create
x-openapi-router-controller: quetzal.app.api.router
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
required: true
responses:
'201':
$ref: '#/components/responses/QueryDetails'
'303':
$ref: '#/components/responses/QueryDetails'
default:
$ref: '#/components/responses/Error'
/data/workspaces/{wid}/queries/{qid}:
parameters:
- name: wid
in: path
description: Workspace identifier.
required: true
schema:
type: integer
- name: qid
in: path
description: Query identifier
required: true
schema:
type: integer
get:
summary: Query details.
description: |-
The details of a query, which contains the query itself and a paginated
list of its results.
tags:
- data
- workspace
- query
operationId: workspace_query.details
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
$ref: '#/components/responses/QueryDetails'
default:
$ref: '#/components/responses/Error'
# Data endpoints (global, committed files)
/data/files/:
get:
summary: List public files.
description: |-
Fetches all the files that have been committed.
The file details included in the response only show their base metadata.
tags:
- data
- public
operationId: public.file_fetch
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/fileFilter'
responses:
'200':
$ref: '#/components/responses/PaginatedFiles'
default:
$ref: '#/components/responses/Error'
/data/files/{uuid}:
parameters:
- name: uuid
in: path
description: File identifier
required: true
schema:
type: string
format: uuid
get:
summary: Fetch public file.
description: |-
This endpoint can be used to fetch the file contents or its metadata.
The type of response, data or metadata, depends on the `Accept`
request header. In the case of metadata, this endpoint returns
the most recent metadata that has been committed.
tags:
- data
- public
operationId: public.file_details
x-openapi-router-controller: quetzal.app.api.router
responses:
'200':
$ref: '#/components/responses/FileContentsOrMetadata'
default:
$ref: '#/components/responses/Error'
/data/queries/:
get:
summary: List public queries.
description: |-
List all the queries that are associated with the global workspace.
Note that each query listed here is shown _without_ its results, for
brevity.
tags:
- data
- public
- query
operationId: public.query_fetch
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
$ref: '#/components/responses/PaginatedQueries'
default:
$ref: '#/components/responses/Error'
post:
summary: Prepare a query.
description: |-
Queries in Quetzal are saved as a resource, in this case, associated
with the global workspace.
This endpoint creates one and responds with a *see other* status
referencing the query details endpoint.
Since the query details contains the query results as a
paginated list, this endpoint also accepts the normal pagination
parameters.
tags:
- data
- public
- query
operationId: public.query_create
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
required: true
responses:
'201':
$ref: '#/components/responses/QueryDetails'
'303':
$ref: '#/components/responses/QueryDetails'
default:
$ref: '#/components/responses/Error'
/data/queries/{qid}:
parameters:
- name: qid
in: path
description: Query identifier
required: true
schema:
type: integer
get:
summary: Query details.
description: |-
The details of a query, which contains the query itself and a paginated
list of its results.
tags:
- data
- workspace
- query
operationId: public.query_details
x-openapi-router-controller: quetzal.app.api.router
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
$ref: '#/components/responses/QueryDetails'
default:
$ref: '#/components/responses/Error'
components:
parameters:
pageOffset:
name: page
in: query
description: The page of a collection to return.
required: false
schema:
type: integer
minimum: 1
default: 1
pageSize:
name: per_page
in: query
description: Number of items to return per page.
schema:
type: integer
minimum: 1
maximum: 100000
default: 100
fileFilter:
name: filters
in: query
description: |-
Filters on the workspace files, separated by commas.
These filters are applied only the base metadata family.
This can be used to get a file by name, path, size or checksum.
schema:
type: string
example:
filename=foo.png,path=images,size=12314
schemas:
Error:
type: object
description: |-
Error object.
An error object used on throughout the Quetzal API to describe errors
and its details following the problem description object defined in
[RFC-7807](https://tools.ietf.org/html/rfc7807).
properties:
type:
description: A URI reference that identifies the problem type.
type: string
example: https://quetz.al/problems/some-name
title:
description: A short, human-readable summary of the problem type.
type: string
example: Bad request.
status:
description: The HTTP status code.
type: integer
example: 400
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
example: Incorrect foo due to missing bar.
instance:
description: A URI reference that identifies the specific occurrence of the problem.
type: string
example: /some_path/some_id
Token:
type: object
description: |-
Authentication token.
Object for a successful basic authentication, containing a token for
subsequent operations requiring a bearer token authentication.
properties:
token:
description: Token for bearer authentication.
type: string
example: wmBXR7vNj8tO+vSCdlqfJSJNvNAtyXr7
required:
- token
PaginationEnvelope:
type: object
description: |-
Paginated response template type.
An envelope for responses that need to be paginated. When a collection
is accessed through a GET request, the results are sent in an object
that informs on the pagination status (page, number of pages, number
of results) and the data itself. This type is heavily inspired from
linode's PaginationEnvelope.
required:
- pages
- page
- total
- results
properties:
page:
type: integer
description: Current page number
readOnly: true
example: 1
pages:
type: integer
description: Number of pages available in the collection
readOnly: true
example: 3
total:
type: integer
description: Total number of items in the collection
readOnly: true
example: 3
results:
type: array
description: Array of objects with the results of the current page
readOnly: true
items:
type: object
example:
- id: 1
- id: 2
- id: 3
Workspace:
description: Workspace details type.
required:
- name
- description
- families
type: object
properties:
id:
description: Workspace ID
type: integer
readOnly: true
example: 1
status:
description: Workspace status
enum:
- INITIALIZING
- READY
- SCANNING
- UPDATING
- COMMITTING
- DELETING
- INVALID
- CONFLICT
- DELETED
readOnly: true
example: READY
creation_date:
format: date-time
description: Date when the workspace was created
type: string
readOnly: true
example: 2019-02-28T09:37:05.618034+00:00
owner:
description: User who owns this workpace
type: string
readOnly: true
example: username
data_url:
description: URL of a remote storage location for files used in this workspace
type: string
readOnly: true
nullable: true
example: gs://some_bucket_name
name:
description: Name of the workspace
type: string
example: my_workspace
description:
description: Descriptive text of the purpose of this workspace
type: string
example: Details on the purpose of this workspace.
families:
description: |-
Families and corresponding versions used in this workspace.
This property is a object whose keys are family names and values are
integers.
type: object
example:
base: 30
other: 24
temporary:
description: |-
Whether this workspace is temporary or not. Temporary workspaces
are automatically deleted after some time.
type: boolean
example: false
PaginatedWorkspaces:
description: |-
A paginated list of workspaces, using the PaginationEnvelope template.
type: object
required:
- page
- pages
- total
- results
properties:
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
total:
$ref: '#/components/schemas/PaginationEnvelope/properties/total'
results:
type: array
items:
$ref: '#/components/schemas/Workspace'
BaseMetadata:
description: |-
Minimal metadata of a file.
All files in Quetzal have metadata and this metadata can have whatever
structure the user requires. However, there is a minimal set of
metadata entries, under the "base" family. Quetzal API operations that
list files use this type to describe their results.
type: object
required:
- id
- url
- state
- path
- filename
- checksum
- size
- date
properties:
id:
description: File identifier.
type: string
format: uuid
example: d06861a5-a14c-449c-bc9a-8f547186286a
url:
description: File URL on Quetzal's data bucket.
type: string
format: url
nullable: true
example: gs://data-bucket/d06861a5-a14c-449c-bc9a-8f547186286a
state:
description: File status.
enum:
- READY
- TEMPORARY
- DELETED
example: READY
path:
description: Path of the file.
type: string
example: study/sub_001
filename:
description: File name. This does not include its path.
type: string
example: ecg_data.bin
checksum:
description: MD5 checksum of the file in hexadecimal string.
type: string
example: f15bc88f4e5cea9b3c578591fd3e74fb
size:
description: File size in bytes.
type: integer
minimum: 0
example: 1024
date: # Note format: date-time is not used yet (Needs server implementation)
description: Date when this file was uploaded to Quetzal.
type: string
example: 2019-02-08 15:55:35.236049+00:00
UnstructuredMetadata:
description: |-
Metadata of a file without a specific structure.
All files in Quetzal have metadata and this metadata can have whatever
structure the user requires. This schema is an object without any
requirements.
type: object
example:
id: 311b4303-bd04-447e-ba71-377545ffa27a
foo: var
number: 1.23
arr: [1, 2, 3]
obj:
key: value
MetadataByFamily:
description: |-
Input type for metadata modifications.
type: object
required:
- id
- metadata
properties:
id:
description: File identifier.
type: string
format: uuid
example: d06861a5-a14c-449c-bc9a-8f547186286a
readOnly: true
metadata:
type: object
description: |-
Metadata organized by dictionaries where the key is the family name
and the contents is a dictionary with key:value pairs.
example:
base:
id: 311b4303-bd04-447e-ba71-377545ffa27a
path: study/session/subject
other:
foo: bar
number: 1.2
FileContents:
description: |-
Contents of a file to upload to a workspace.
**Note**: Ideally, we want to add the metadata of the file on this
schema, so that uploading a file contains its metadata and there is no
need to do a second request to set the metadata. Unfortunately, there
are two problems that impede this: