-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
23 changed files
with
296 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| type: object | ||
| description: The object that contains object_id/access_id tuples | ||
| properties: | ||
| passports: | ||
| type: array | ||
| items: | ||
| type: string | ||
| bulk_object_access_ids: | ||
| type: array | ||
| items: | ||
| type: object | ||
| properties: | ||
| bulk_object_id: | ||
| type: string | ||
| description: DRS object ID | ||
| bulk_access_ids: | ||
| type: array | ||
| description: DRS object access ID | ||
| items: | ||
| type: string |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| type: object | ||
| description: The object that contains the DRS object IDs array | ||
| properties: | ||
| passports: | ||
| type: array | ||
| items: | ||
| type: string | ||
| example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYTRnaF9wYXNzcG9ydF92MSI6W119.JJ5rN0ktP0qwyZmIPpxmF_p7JsxAZH6L6brUxtad3CM | ||
| description: the encoded JWT GA4GH Passport that contains embedded Visas. The overall JWT is signed as are the individual Passport Visas. | ||
| bulk_object_ids: | ||
| type: array | ||
| items: | ||
| type: string | ||
| description: An array of ObjectIDs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| type: object | ||
| description: The object that contains the DRS object IDs array | ||
| properties: | ||
| bulk_object_ids: | ||
| type: array | ||
| description: DRS object IDs | ||
| items: | ||
| type: string | ||
| description: An array of ObjectIDs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| type: object | ||
| description: The object that contains an object_id/access_id tuple | ||
| properties: | ||
| bulk_object_id: | ||
| type: string | ||
| bulk_object_access_id: | ||
| type: string |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| description: The `AccessURL` was found successfully | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| summary: | ||
| $ref: '../schemas/summary.yaml' | ||
| unresolved_drs_objects: | ||
| $ref: '../schemas/unresolved.yaml' | ||
| resolved_drs_object_access_urls: | ||
| type: array | ||
| items: | ||
| $ref: '../schemas/BulkAccessURL.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| description: "`Authorizations` were found successfully" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| summary: | ||
| $ref: '../schemas/summary.yaml' | ||
| unresolved_drs_objects: | ||
| $ref: '../schemas/unresolved.yaml' | ||
| resolved_drs_object: | ||
| type: array | ||
| items: | ||
| $ref: '../schemas/Authorizations.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| description: The `DrsObjects` were found successfully | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| summary: | ||
| $ref: '../schemas/summary.yaml' | ||
| unresolved_drs_objects: | ||
| $ref: '../schemas/unresolved.yaml' | ||
| resolved_drs_object: | ||
| type: array | ||
| items: | ||
| $ref: '../schemas/DrsObject.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| description: The bulk request is too large. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../schemas/Error.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,7 @@ | ||
| type: object | ||
| properties: | ||
| drs_object_id: | ||
| type: string | ||
| supported_types: | ||
| type: array | ||
| items: | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| type: object | ||
| required: | ||
| - url | ||
| properties: | ||
| drs_object_id: | ||
| type: string | ||
| drs_access_id: | ||
| type: string | ||
| url: | ||
| type: string | ||
| description: A fully resolvable URL that can be used to fetch the actual object bytes. | ||
| headers: | ||
| type: array | ||
| items: | ||
| type: string | ||
| description: >- | ||
| An optional list of headers to include in the HTTP request to `url`. | ||
| These headers can be used to provide auth tokens required to fetch the object bytes. | ||
| example: 'Authorization: Basic Z2E0Z2g6ZHJz' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| type: object | ||
| description: A summary of what was resolved. | ||
| properties: | ||
| requested: | ||
| type: integer | ||
| description: Number of items requested. | ||
| resolved: | ||
| type: integer | ||
| description: Number of objects resolved. | ||
| unresolved: | ||
| type: integer | ||
| description: Number of objects not resolved. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| type: array | ||
| description: Error codes for each unresolved drs objects. | ||
| items: | ||
| type: object | ||
| properties: | ||
| error_code: | ||
| type: integer | ||
| object_ids: | ||
| type: array | ||
| items: | ||
| type: string |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| post: | ||
| summary: Get URLs for fetching bytes from multiple objects with an optional Passport(s). | ||
| description: >- | ||
| Returns an array of URL objects that can be used to fetch the bytes of multiple `DrsObject`s. | ||
| This method only needs to be called when using an `AccessMethod` that contains an `access_id` | ||
| (e.g., for servers that use signed URLs for fetching object bytes). | ||
| Currently this is limited to use passports (one or more) or a single bearer token, so make sure your bulk request is for objects that all use the same passports/token. | ||
| operationId: GetBulkAccessURL | ||
| security: | ||
| - PassportAuth: [] | ||
| responses: | ||
| 200: | ||
| $ref: '../components/responses/200OkAccesses.yaml' | ||
| 202: | ||
| $ref: '../components/responses/202Accepted.yaml' | ||
| 400: | ||
| $ref: '../components/responses/400BadRequest.yaml' | ||
| 401: | ||
| $ref: '../components/responses/401Unauthorized.yaml' | ||
| 403: | ||
| $ref: '../components/responses/403Forbidden.yaml' | ||
| 404: | ||
| $ref: '../components/responses/404NotFoundAccess.yaml' | ||
| 413: | ||
| $ref: '../components/responses/413RequestTooLarge.yaml' | ||
| 500: | ||
| $ref: '../components/responses/500InternalServerError.yaml' | ||
| tags: | ||
| - Objects | ||
| x-swagger-router-controller: ga4gh.drs.server | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../components/parameters/BulkObjectAccessId.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| options: | ||
| summary: Get Authorization info about multiple DrsObjects. | ||
| security: | ||
| - {} | ||
| description: >- | ||
| Returns a structure that contains for each DrsObjects a list of `Authorizations` that can be used to determine how to authorize requests to `GetObject` or `PostObject` (or bulk equivalents). | ||
| operationId: OptionsBulkObject | ||
| responses: | ||
| 200: | ||
| $ref: '../components/responses/200OkBulkAuthorizations.yaml' | ||
| 204: | ||
| $ref: '../components/responses/AuthorizationsNotSupported.yaml' | ||
| 400: | ||
| $ref: '../components/responses/400BadRequest.yaml' | ||
| 404: | ||
| $ref: '../components/responses/404NotFoundDrsObject.yaml' | ||
| 405: | ||
| $ref: '../components/responses/AuthorizationsNotSupported.yaml' | ||
| 413: | ||
| $ref: '../components/responses/413RequestTooLarge.yaml' | ||
| 500: | ||
| $ref: '../components/responses/500InternalServerError.yaml' | ||
| tags: | ||
| - Objects | ||
| x-swagger-router-controller: ga4gh.drs.server | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../components/parameters/BulkObjectIdNoPassport.yaml' | ||
|
|
||
| post: | ||
| summary: Get info about multiple DrsObjects with an optional Passport(s). | ||
| description: >- | ||
| Returns an array of object metadata, and a list of access methods that can be used to fetch objects' bytes. Currently this is limited to use passports (one or more) or a single bearer token, so make sure your bulk request is for objects that all use the same passports/token. | ||
| operationId: GetBulkObjects | ||
| security: | ||
| - PassportAuth: [] | ||
| parameters: | ||
| - $ref: '../components/parameters/Expand.yaml' | ||
| responses: | ||
| 200: | ||
| $ref: '../components/responses/200OkDrsObjects.yaml' | ||
| 202: | ||
| $ref: '../components/responses/202Accepted.yaml' | ||
| 400: | ||
| $ref: '../components/responses/400BadRequest.yaml' | ||
| 401: | ||
| $ref: '../components/responses/401Unauthorized.yaml' | ||
| 403: | ||
| $ref: '../components/responses/403Forbidden.yaml' | ||
| 404: | ||
| $ref: '../components/responses/404NotFoundDrsObject.yaml' | ||
| 413: | ||
| $ref: '../components/responses/413RequestTooLarge.yaml' | ||
| 500: | ||
| $ref: '../components/responses/500InternalServerError.yaml' | ||
| tags: | ||
| - Objects | ||
| x-swagger-router-controller: ga4gh.drs.server | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../components/parameters/BulkObjectId.yaml' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| ## Compound Objects | ||
|
|
||
| The DRS API supports access to data objects, with each `DrsObject` representing a single opaque blob of bytes. Much content (e.g. VCF files) is well represented as a single atomic `DrsObject`. Some content, however (e.g. DICOM images) is best represented as a compound object consisting of a structured collection of atomic `DrsObject`s. In both cases, DRS isn't aware of the semantics of the objects it serves -- understanding those semantics is the responsibility of the applications that call DRS. | ||
|
|
||
| Common examples of compound objects in biomedicine include: | ||
| * BAM+BAI genomic reads, with a small index (the BAI object) to large data (the BAM object), each object using a well-defined file format. | ||
| * DICOM images, with a contents object pointing to one or more raw image objects, each containing pixels from different aspects of a single logical biomedical image (e.g. different z-coordinates) | ||
| * studies, with a single table of contents listing multiple objects of various types that were generated together and are meant to be processed together | ||
|
|
||
| ## Best Practice: Manifests | ||
|
|
||
| As with atomic objects, DRS applications and servers are expected to agree on the semantics of compound objects using non-DRS mechanisms. The recommended best practice for representing a particular compound object type is: | ||
| 1. Define a manifest file syntax, which contains the DRS IDs of the constituent atomic objects, plus type-specific information about the relationship between those constituents. | ||
| * Manifest file syntax isn't prescribed by the spec, but we expect they will often be JSON files. | ||
| * For example, for a BAM+BAI pair the manifest file could contain two key-value pairs mapping the type of each constituent file to its DRS ID. | ||
| 3. Make manifest objects and their constituent objects available using standard DRS mechanisms -- each object is referenced via its own DRS ID, just like any other atomic object. | ||
| * For example, for a BAM+BAI pair, there would be three DRS IDs -- one for the manifest, one for the BAM, and one for the BAI. | ||
| 5. Document the expected client logic for processing compound objects of interest. This logic typically consists of using standard DRS mechanisms to fetch the manifest, parsing its syntax, extracting the DRS IDs of constituent objects, and using standard DRS mechanisms to fetch the constituents as needed. | ||
| * In some cases the application will always want to fetch all of the constituents; in other cases it may want to initially fetch a subset, and only fetch the others on demand. For example, a DICOM image viewer may only want to fetch the layers that are being rendered. |
Oops, something went wrong.