diff --git a/openapi/data_repository_service.swagger.yaml b/openapi/data_repository_service.swagger.yaml index 2e023d37b..927568f38 100644 --- a/openapi/data_repository_service.swagger.yaml +++ b/openapi/data_repository_service.swagger.yaml @@ -1,406 +1,379 @@ -swagger: '2.0' -basePath: '/ga4gh/drs/v1' +openapi: 3.0.1 info: title: Data Repository Service - version: 1.1.0 - description: 'https://github.com/ga4gh/data-repository-service-schemas' - termsOfService: 'https://www.ga4gh.org/terms-and-conditions/' + description: https://github.com/ga4gh/data-repository-service-schemas + termsOfService: https://www.ga4gh.org/terms-and-conditions/ contact: name: GA4GH Cloud Work Stream email: ga4gh-cloud@ga4gh.org license: name: Apache 2.0 - url: 'https://raw.githubusercontent.com/ga4gh/data-repository-service-schemas/master/LICENSE' -schemes: - - https -consumes: - - application/json -produces: - - application/json + url: https://raw.githubusercontent.com/ga4gh/data-repository-service-schemas/master/LICENSE + version: 1.1.0 +servers: +- url: /ga4gh/drs/v1 security: - - {} - - authToken: [] +- {} +- authToken: [] +tags: +- name: DataRepositoryService paths: - '/objects/{object_id}': + /objects/{object_id}: get: + tags: + - DataRepositoryService summary: Get info about a `DrsObject`. - description: >- - Returns object metadata, and a list of access methods that can be used to fetch object bytes. + description: Returns object metadata, and a list of access methods that can + be used to fetch object bytes. operationId: GetObject + parameters: + - name: object_id + in: path + required: true + schema: + type: string + - name: expand + in: query + description: |- + If false and the object_id refers to a bundle, then the ContentsObject array contains only those objects directly contained in the bundle. That is, if the bundle contains other bundles, those other bundles are not recursively included in the result. + If true and the object_id refers to a bundle, then the entire set of objects in the bundle is expanded. That is, if the bundle contains aother bundles, then those other bundles are recursively expanded and included in the result. Recursion continues through the entire sub-tree of the bundle. + If the object_id refers to a blob, then the query parameter is ignored. + schema: + type: boolean + default: false responses: - '200': + 200: description: The `DrsObject` was found successfully. - schema: - $ref: '#/definitions/DrsObject' - '202': - description: > - The operation is delayed and will continue asynchronously. - The client should retry this same request after the delay specified by Retry-After header. + content: + application/json: + schema: + $ref: '#/components/schemas/DrsObject' + 202: + description: | + The operation is delayed and will continue asynchronously. The client should retry this same request after the delay specified by Retry-After header. headers: Retry-After: - description: > - Delay in seconds. The client should retry this same request after waiting for this duration. - To simplify client response processing, this must be an integral relative time in seconds. - This value SHOULD represent the minimum duration the client should wait before attempting - the operation again with a reasonable expectation of success. When it is not feasible - for the server to determine the actual expected delay, the server may return a - brief, fixed value instead. - type: integer - format: int64 - '400': + description: | + Delay in seconds. The client should retry this same request after waiting for this duration. To simplify client response processing, this must be an integral relative time in seconds. This value SHOULD represent the minimum duration the client should wait before attempting the operation again with a reasonable expectation of success. When it is not feasible for the server to determine the actual expected delay, the server may return a brief, fixed value instead. + schema: + type: integer + format: int64 + content: {} + 400: description: The request is malformed. - schema: - $ref: '#/definitions/Error' - '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 401: description: The request is unauthorized. - schema: - $ref: '#/definitions/Error' - '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: description: The requester is not authorized to perform this action. - schema: - $ref: '#/definitions/Error' - '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 404: description: The requested `DrsObject` wasn't found - schema: - $ref: '#/definitions/Error' - '500': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 500: description: An unexpected error occurred. - schema: - $ref: '#/definitions/Error' - parameters: - - name: object_id - in: path - required: true - type: string - - in: query - name: expand - type: boolean - default: false - description: >- - If false and the object_id refers to a bundle, then the ContentsObject array - contains only those objects directly contained in the bundle. That is, if the - bundle contains other bundles, those other bundles are not recursively - included in the result. - - If true and the object_id refers to a bundle, then the entire set of objects - in the bundle is expanded. That is, if the bundle contains aother bundles, - then those other bundles are recursively expanded and included in the result. - Recursion continues through the entire sub-tree of the bundle. - - If the object_id refers to a blob, then the query parameter is ignored. - tags: - - DataRepositoryService + content: + application/json: + schema: + $ref: '#/components/schemas/Error' x-swagger-router-controller: ga4gh.drs.server - '/objects/{object_id}/access/{access_id}': + /objects/{object_id}/access/{access_id}: get: + tags: + - DataRepositoryService summary: Get a URL for fetching bytes. - description: >- + description: |- Returns a URL that can be used to fetch the bytes of a `DrsObject`. - - 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). + 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). operationId: GetAccessURL + parameters: + - name: object_id + in: path + description: An `id` of a `DrsObject` + required: true + schema: + type: string + - name: access_id + in: path + description: An `access_id` from the `access_methods` list of a `DrsObject` + required: true + schema: + type: string responses: - '200': + 200: description: The access URL was found successfully. - schema: - $ref: '#/definitions/AccessURL' - '202': - description: > - The operation is delayed and will continue asynchronously. - The client should retry this same request after the delay specified by Retry-After header. + content: + application/json: + schema: + $ref: '#/components/schemas/AccessURL' + 202: + description: | + The operation is delayed and will continue asynchronously. The client should retry this same request after the delay specified by Retry-After header. headers: Retry-After: - description: > - Delay in seconds. The client should retry this same request after waiting for this duration. - To simplify client response processing, this must be an integral relative time in seconds. - This value SHOULD represent the minimum duration the client should wait before attempting - the operation again with a reasonable expectation of success. When it is not feasible - for the server to determine the actual expected delay, the server may return a - brief, fixed value instead. - type: integer - format: int64 - '400': + description: | + Delay in seconds. The client should retry this same request after waiting for this duration. To simplify client response processing, this must be an integral relative time in seconds. This value SHOULD represent the minimum duration the client should wait before attempting the operation again with a reasonable expectation of success. When it is not feasible for the server to determine the actual expected delay, the server may return a brief, fixed value instead. + schema: + type: integer + format: int64 + content: {} + 400: description: The request is malformed. - schema: - $ref: '#/definitions/Error' - '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 401: description: The request is unauthorized. - schema: - $ref: '#/definitions/Error' - '404': - description: The requested access URL wasn't found - schema: - $ref: '#/definitions/Error' - '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: description: The requester is not authorized to perform this action. - schema: - $ref: '#/definitions/Error' - '500': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 404: + description: The requested access URL wasn't found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 500: description: An unexpected error occurred. - schema: - $ref: '#/definitions/Error' - parameters: - - name: object_id - in: path - required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-swagger-router-controller: ga4gh.drs.server +components: + schemas: + Checksum: + required: + - checksum + - type + type: object + properties: + checksum: type: string - description: An `id` of a `DrsObject` - - name: access_id - in: path - required: true + description: The hex-string encoded checksum for the data + type: type: string - description: An `access_id` from the `access_methods` list of a `DrsObject` - tags: - - DataRepositoryService - x-swagger-router-controller: ga4gh.drs.server -securityDefinitions: - authToken: - description: | - A valid authorization token must be passed in the 'Authorization' header. - Example syntax for using 'Authorization' header : - Bearer: token_string - type: apiKey - name: Authorization - in: header -definitions: - Checksum: - type: object - required: ['checksum', 'type'] - properties: - checksum: - type: string - description: 'The hex-string encoded checksum for the data' - type: - type: string - description: >- - The digest method used to create the checksum. - + description: |- + The digest method used to create the checksum. - The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg[IANA Named Information Hash Algorithm Registry]. - Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920]. + The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg[IANA Named Information Hash Algorithm Registry]. Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920]. + GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future. Until then, if implementors do choose such an algorithm (e.g. because it's implemented by their storage provider), they SHOULD use an existing standard `type` value such as `md5`, `etag`, `crc32c`, `trunc512`, or `sha1`. + example: sha-256 + DrsObject: + required: + - checksums + - created_time + - id + - self_uri + - size + type: object + properties: + id: + type: string + description: An identifier unique to this `DrsObject`. + name: + type: string + description: |- + A string that can be used to name a `DrsObject`. + This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames]. + self_uri: + type: string + description: |- + A drs:// hostname-based URI, as defined in the DRS documentation, that tells clients how to access this object. + The intent of this field is to make DRS objects self-contained, and therefore easier for clients to store and pass around. For example, if you arrive at this DRS JSON by resolving a compact identifier-based DRS URI, the `self_uri` presents you with a hostname and properly encoded DRS ID for use in subsequent `access` endpoint calls. + example: drs://drs.example.org/314159 + size: + type: integer + description: |- + For blobs, the blob size in bytes. + For bundles, the cumulative size, in bytes, of items in the `contents` field. + format: int64 + created_time: + type: string + description: |- + Timestamp of content creation in RFC3339. + (This is the creation time of the underlying content, not of the JSON object.) + format: date-time + updated_time: + type: string + description: Timestamp of content update in RFC3339, identical to `created_time` + in systems that do not support updates. (This is the update time of the + underlying content, not of the JSON object.) + format: date-time + version: + type: string + description: |- + A string representing a version. + (Some systems may use checksum, a RFC3339 timestamp, or an incrementing version number.) + mime_type: + type: string + description: A string providing the mime-type of the `DrsObject`. + example: application/json + checksums: + minItems: 1 + type: array + description: |- + The checksum of the `DrsObject`. At least one checksum must be provided. + For blobs, the checksum is computed over the bytes in the blob. - GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future. - Until then, if implementors do choose such an algorithm (e.g. because it's implemented by their storage provider), they SHOULD use an existing - standard `type` value such as `md5`, `etag`, `crc32c`, `trunc512`, or `sha1`. - example: - sha-256 - DrsObject: - type: object - required: ['id', 'self_uri', 'size', 'created_time', 'checksums'] - properties: - id: - type: string - description: |- - An identifier unique to this `DrsObject`. - name: - type: string - description: |- - A string that can be used to name a `DrsObject`. - This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames]. - self_uri: - type: string - description: |- - A drs:// hostname-based URI, as defined in the DRS documentation, that tells clients how to access this object. - The intent of this field is to make DRS objects self-contained, and therefore easier for clients to store and pass around. For example, if you arrive at this DRS JSON by resolving a compact identifier-based DRS URI, the `self_uri` presents you with a hostname and properly encoded DRS ID for use in subsequent `access` endpoint calls. - example: - drs://drs.example.org/314159 - size: - type: integer - format: int64 - description: |- - For blobs, the blob size in bytes. - For bundles, the cumulative size, in bytes, of items in the `contents` field. - created_time: - type: string - format: date-time - description: |- - Timestamp of content creation in RFC3339. - (This is the creation time of the underlying content, not of the JSON object.) - updated_time: - type: string - format: date-time - description: >- - Timestamp of content update in RFC3339, identical to `created_time` in systems - that do not support updates. - (This is the update time of the underlying content, not of the JSON object.) - version: - type: string - description: >- - A string representing a version. - - (Some systems may use checksum, a RFC3339 timestamp, or an incrementing version number.) - mime_type: - type: string - description: |- - A string providing the mime-type of the `DrsObject`. - example: - application/json - checksums: - type: array - minItems: 1 - items: - $ref: '#/definitions/Checksum' - description: >- - The checksum of the `DrsObject`. At least one checksum must be provided. - - For blobs, the checksum is computed over the bytes in the blob. - - - For bundles, the checksum is computed over a sorted concatenation of the - checksums of its top-level contained objects (not recursive, names not included). - The list of checksums is sorted alphabetically (hex-code) before concatenation - and a further checksum is performed on the concatenated checksum value. - - - For example, if a bundle contains blobs with the following checksums: - - md5(blob1) = 72794b6d - - md5(blob2) = 5e089d29 - - - Then the checksum of the bundle is: - - md5( concat( sort( md5(blob1), md5(blob2) ) ) ) - - = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) - - = md5( concat( 5e089d29, 72794b6d ) ) - - = md5( 5e089d2972794b6d ) + For bundles, the checksum is computed over a sorted concatenation of the checksums of its top-level contained objects (not recursive, names not included). The list of checksums is sorted alphabetically (hex-code) before concatenation and a further checksum is performed on the concatenated checksum value. - = f7a29a04 - access_methods: - type: array - minItems: 1 - items: - $ref: '#/definitions/AccessMethod' - description: |- - The list of access methods that can be used to fetch the `DrsObject`. - Required for single blobs; optional for bundles. - contents: - type: array - description: >- - If not set, this `DrsObject` is a single blob. + For example, if a bundle contains blobs with the following checksums: + md5(blob1) = 72794b6d + md5(blob2) = 5e089d29 - If set, this `DrsObject` is a bundle containing the listed `ContentsObject` s (some of which may be further nested). - items: - $ref: '#/definitions/ContentsObject' - description: - type: string - description: |- - A human readable description of the `DrsObject`. - aliases: - type: array - items: + Then the checksum of the bundle is: + md5( concat( sort( md5(blob1), md5(blob2) ) ) ) + = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) + = md5( concat( 5e089d29, 72794b6d ) ) + = md5( 5e089d2972794b6d ) + = f7a29a04 + items: + $ref: '#/components/schemas/Checksum' + access_methods: + minItems: 1 + type: array + description: |- + The list of access methods that can be used to fetch the `DrsObject`. + Required for single blobs; optional for bundles. + items: + $ref: '#/components/schemas/AccessMethod' + contents: + type: array + description: |- + If not set, this `DrsObject` is a single blob. + If set, this `DrsObject` is a bundle containing the listed `ContentsObject` s (some of which may be further nested). + items: + $ref: '#/components/schemas/ContentsObject' + description: type: string - description: >- - A list of strings that can be used to find other metadata - about this `DrsObject` from external metadata sources. These - aliases can be used to represent secondary - accession numbers or external GUIDs. - AccessURL: - type: object - required: ['url'] - properties: - url: - type: string - description: A fully resolvable URL that can be used to fetch the actual object bytes. - headers: - type: array - items: + description: A human readable description of the `DrsObject`. + aliases: + type: array + description: A list of strings that can be used to find other metadata about + this `DrsObject` from external metadata sources. These aliases can be + used to represent secondary accession numbers or external GUIDs. + items: + type: string + AccessURL: + required: + - url + type: object + properties: + url: 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 - AccessMethod: - type: object - required: + description: A fully resolvable URL that can be used to fetch the actual + object bytes. + headers: + type: array + 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 + items: + type: string + AccessMethod: + required: - type - properties: - type: - type: string - enum: - - s3 - - gs - - ftp - - gsiftp - - globus - - htsget - - https - - file - description: >- - Type of the access method. - access_url: - $ref: '#/definitions/AccessURL' - description: >- - An `AccessURL` that can be used to fetch the actual object bytes. - Note that at least one of `access_url` and `access_id` must be provided. - access_id: - type: string - description: >- - An arbitrary string to be passed to the `/access` method to get an `AccessURL`. - This string must be unique within the scope of a single object. - Note that at least one of `access_url` and `access_id` must be provided. - region: - type: string - description: >- - Name of the region in the cloud service provider that the object belongs to. - example: - us-east-1 - Error: - description: - An object that can optionally include information about the error. - type: object - properties: - msg: - type: string - description: A detailed error message. - status_code: - type: integer - description: The integer representing the HTTP status code (e.g. 200, 404). - ContentsObject: - type: object - properties: - name: - type: string - description: >- - A name declared by the bundle author that must be - used when materialising this object, - overriding any name directly associated with the object itself. - The name must be unique with the containing bundle. - This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames]. - id: - type: string - description: >- - A DRS identifier of a `DrsObject` (either a single blob or a nested bundle). - If this ContentsObject is an object within a nested bundle, then the id is - optional. Otherwise, the id is required. - drs_uri: - type: array - description: >- - A list of full DRS identifier URI paths - that may be used to obtain the object. - These URIs may be external to this DRS instance. - example: - drs://drs.example.org/314159 - items: + type: object + properties: + type: type: string - contents: - type: array - description: >- - If this ContentsObject describes a nested bundle and the caller specified - "?expand=true" on the request, then this contents array must be present and - describe the objects within the nested bundle. - items: - $ref: '#/definitions/ContentsObject' - - required: + description: Type of the access method. + enum: + - s3 + - gs + - ftp + - gsiftp + - globus + - htsget + - https + - file + access_url: + $ref: '#/components/schemas/AccessURL' + access_id: + type: string + description: An arbitrary string to be passed to the `/access` method to + get an `AccessURL`. This string must be unique within the scope of a single + object. Note that at least one of `access_url` and `access_id` must be + provided. + region: + type: string + description: Name of the region in the cloud service provider that the object + belongs to. + example: us-east-1 + Error: + type: object + properties: + msg: + type: string + description: A detailed error message. + status_code: + type: integer + description: The integer representing the HTTP status code (e.g. 200, 404). + description: An object that can optionally include information about the error. + ContentsObject: + required: - name -tags: - - name: DataRepositoryService + type: object + properties: + name: + type: string + description: A name declared by the bundle author that must be used when + materialising this object, overriding any name directly associated with + the object itself. The name must be unique with the containing bundle. + This string is made up of uppercase and lowercase letters, decimal digits, + hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable + filenames]. + id: + type: string + description: A DRS identifier of a `DrsObject` (either a single blob or + a nested bundle). If this ContentsObject is an object within a nested + bundle, then the id is optional. Otherwise, the id is required. + drs_uri: + type: array + description: A list of full DRS identifier URI paths that may be used to + obtain the object. These URIs may be external to this DRS instance. + example: drs://drs.example.org/314159 + items: + type: string + contents: + type: array + description: If this ContentsObject describes a nested bundle and the caller + specified "?expand=true" on the request, then this contents array must + be present and describe the objects within the nested bundle. + items: + $ref: '#/components/schemas/ContentsObject' + securitySchemes: + authToken: + type: apiKey + description: | + A valid authorization token must be passed in the 'Authorization' header. + Example syntax for using 'Authorization' header : + Bearer: token_string + name: Authorization + in: header