openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user DOS 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: DOS
  description: Data Object Service Retrieval Endpoints
paths:
  /ga4gh/dos/v1/dataobjects:
    get:
      summary: List the Data Objects
      operationId: ListDataObjects
      responses:
        '200':
          description: The Data Objects were listed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataObjectsResponse'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The requester is not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: alias
        in: query
        required: false
        description: If provided will only return Data Objects with the given alias.
        schema:
          type: string
      - name: url
        in: query
        required: false
        description: 'If provided will return only Data Objects with a that URL matches

          this string.'
        schema:
          type: string
      - name: checksum
        in: query
        required: false
        description: The hexlified checksum that one would like to match on.
        schema:
          type: string
      - name: checksum_type
        in: query
        required: false
        description: 'If provided will restrict responses to those that match the provided

          type.

          possible values:

          md5                # most blob stores provide a checksum using this

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

          sha256

          sha512'
        schema:
          type: string
      - name: page_size
        in: query
        required: false
        description: 'Specifies the maximum number of results to return in a single page.

          If unspecified, a system default will be used.'
        schema:
          type: integer
          format: int32
      - name: page_token
        in: query
        required: false
        description: 'The continuation token, which is used to page through large result sets.

          To get the next page of results, set this parameter to the value of

          next_page_token from the previous response.'
        schema:
          type: string
      tags:
      - DOS
  /ga4gh/dos/v1/dataobjects/{GUID}:
    get:
      summary: Retrieve a Data Object
      operationId: GetDataObject
      responses:
        '200':
          description: The Data Object was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDataObjectResponse'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested Data Object wasn't found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The requester is not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: GUID
        in: path
        required: true
        schema:
          type: string
      tags:
      - DOS
components:
  schemas:
    SystemMetadata:
      type: object
      additionalProperties: true
      description: 'OPTIONAL

        These values are reported by the underlying object store.

        A set of key-value pairs that represent system metadata about the object.'
    ListDataObjectsResponse:
      type: object
      properties:
        data_objects:
          type: array
          items:
            $ref: '#/components/schemas/DataObject'
          description: The list of Data Objects.
        next_page_token:
          type: string
          description: 'The continuation token, which is used to page through large result sets.

            Provide this value in a subsequent request to return the next page of

            results. This field will be empty if there aren''t any additional results.'
      description: 'A list of Data Objects matching the requested parameters, and a paging

        token, that can be used to retrieve more results.'
    URL:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: A URL that can be used to access the file.
        system_metadata:
          $ref: '#/components/schemas/SystemMetadata'
        user_metadata:
          $ref: '#/components/schemas/UserMetadata'
    UserMetadata:
      type: object
      additionalProperties: true
      description: 'OPTIONAL

        A set of key-value pairs that represent metadata provided by the uploader.'
    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'
    ErrorResponse:
      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).
    DataObject:
      type: object
      required:
      - id
      - size
      - created
      - checksums
      properties:
        id:
          type: string
          description: An identifier unique to this Data Object.
        name:
          type: string
          description: A string that can be optionally used to name a Data Object.
        size:
          type: string
          format: int64
          description: The computed size in bytes.
        created:
          type: string
          format: date-time
          description: Timestamp of object creation in RFC3339.
        updated:
          type: string
          format: date-time
          description: 'Timestamp of update in RFC3339, identical to create timestamp in systems

            that do not support updates.'
        version:
          type: string
          description: A string representing a version.
        mime_type:
          type: string
          description: 'A string providing the mime-type of the Data Object.

            For example, "application/json".'
        checksums:
          type: array
          items:
            $ref: '#/components/schemas/Checksum'
          description: The checksum of the Data Object. At least one checksum must be provided.
        urls:
          type: array
          items:
            $ref: '#/components/schemas/URL'
          description: The list of URLs that can be used to access the Data Object.
        description:
          type: string
          description: A human readable description of the contents of the Data Object.
        aliases:
          type: array
          items:
            type: string
          description: 'A list of strings that can be used to find this Data Object.

            These aliases can be used to represent the Data Object''s location in

            a directory (e.g. "bucket/folder/file.name") to make Data Objects

            more discoverable. They might also be used to represent'
    GetDataObjectResponse:
      type: object
      required:
      - data_object
      properties:
        data_object:
          $ref: '#/components/schemas/DataObject'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access