University of Chicago DRS API

openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user DRS API
  version: 0.1.0
  description: Access management for Gen3 data commons. Code is available on [GitHub](https://github.com/uc-cdis/fence).
  termsOfService: http://cdis.uchicago.edu/terms/
  contact:
    email: cdis@uchicago.edu
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://example.domain/
tags:
- name: DRS
  description: Data Repository Service Retrieval Endpoints
paths:
  /ga4gh/drs/v1/objects:
    get:
      summary: List all DrsObject.
      description: Url field here contains their location and not the presigned url.
      operationId: ListDrsObject
      parameters:
      - name: form
        in: query
        description: specify whether you want to list bundle, objects or both.
        required: false
        schema:
          type: string
          enum:
          - bundle
          - object
          - all
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDrsObject'
      security: []
      tags:
      - DRS
  /ga4gh/drs/v1/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. Resolves for bundles.
      operationId: GetObject
      responses:
        '200':
          description: The DrsObject was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrsObject'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The request is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The requester is not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The requested DrsObject wasn't found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: object_id
        in: path
        required: true
        schema:
          type: string
      - in: query
        name: expand
        description: 'NOT IMPLEMENTED YET.

          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
      x-swagger-router-controller: ga4gh.drs.server
      security:
      - authToken: []
      tags:
      - DRS
components:
  schemas:
    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:// 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.'
          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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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.
    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:
            example: {}
      required:
      - name
    AccessURL:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: A fully resolvable URL that can be used to fetch the actual object bytes.
    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: '#/components/schemas/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
    Checksum:
      type: object
      required:
      - checksum
      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. If left unspecified md5

            will be assumed.

            possible values:

            md5                # most blob stores provide a checksum using this

            multipart-md5      # multipart uploads provide a specialized tag in S3

            sha256

            sha512'
    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).
    ListDrsObject:
      type: object
      properties:
        drs_objects:
          type: array
          items:
            $ref: '#/components/schemas/DrsObject'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access