swagger: '2.0'
basePath: '/ga4gh/drs/v1'
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/'
  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
security:
  - {}
  - authToken: []
paths:
  '/objects/{object_id}':
    get:
      summary: Get info about a `DrsObject`.
      description: >-
        Returns object metadata, and a list of access methods that can be used to fetch object bytes.
      operationId: GetObject
      responses:
        '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.
          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: The request is malformed.
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: The request is unauthorized.
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: The requester is not authorized to perform this action.
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: The requested `DrsObject` wasn't found
          schema:
            $ref: '#/definitions/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
      x-swagger-router-controller: ga4gh.drs.server
  '/objects/{object_id}/access/{access_id}':
    get:
      summary: Get a URL for fetching bytes.
      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).
      operationId: GetAccessURL
      responses:
        '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.
          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: The request is malformed.
          schema:
            $ref: '#/definitions/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':
          description: The requester is not authorized to perform this action.
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: An unexpected error occurred.
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - name: object_id
          in: path
          required: true
          type: string
          description: An `id` of a `DrsObject`
        - name: access_id
          in: path
          required: true
          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.


          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:
    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 )

          = 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.

          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:
          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:
          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:
      - 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: 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:
      - name
tags:
  - name: DataRepositoryService