Dryad Files API

openapi: 3.2.0
info:
  title: Dryad Files API
  description: Dryad's REST API allows detailed interaction and programmatic interfacing with Dryad contents.
  version: 2.1.0
servers:
- url: https://datadryad.org/api/v2
  description: Main Dryad server
- url: https://sandbox.datadryad.org/api/v2
  description: Sandbox server, for testing new features.
tags:
- name: Files
  description: Operations on individual files of a dataset
paths:
  /files/{id}:
    get:
      summary: Get metadata information about a file
      tags:
      - Files
      description: Returns file metadata information visible to the user (or public) by the file ID. The version file list embeds this metadata and also lists the file IDs.
      parameters:
      - $ref: '#/components/parameters/file_id'
      responses:
        '200':
          description: A single file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
              examples:
                success:
                  $ref: api/v2/docs/examples/file.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getFilesById
      x-operation-id-source: derived
    delete:
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/file_id'
      summary: Remove a file from an in-progress dataset version
      tags:
      - Files
      description: This action only works on an in-progress dataset (this means that the latest version of a dataset associated with this file has to be in-progress). It will destroy the metadata and file if it's a staged file that hasn't been submitted to the repository yet. If the file was submitted previously in an earlier version of the same dataset it will stage removal from the in-progress dataset version. In order to finalize staged file changes into the storage repository, the in-progress dataset must be submitted again after all changes are ready.
      responses:
        '201':
          description: The file and metadata was removed from staging.  Or the file and metadata was staged for removal from this version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
              examples:
                success:
                  $ref: api/v2/docs/examples/file.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: This file must be part of an an in-progress version.
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteFilesById
      x-operation-id-source: derived
  /files/{id}/download:
    get:
      summary: Download a specific file
      tags:
      - Files
      description: Only files that have been stored in the storage repository may be downloaded (and ability to download may depend on the user). Versions of a dataset still in-progress only have staged files that may not be downloaded until they have been submitted to the storage repository.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/file_id'
      responses:
        '200':
          description: The binary content of the file downloads as the http body.  The "Content-Type" and "Content-Disposition" headers will be set to reflect the file content-type and filename when downloading (following http standards).
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getFilesByIdDownload
      x-operation-id-source: derived
  /datasets/{doi}/files/{filename}:
    put:
      summary: Upload and stage a file for an in-progress dataset
      tags:
      - Files
      description: Allows uploading a file to be staged for submission to the storage repository. The files will be stored in the storage repository after the dataset is submitted. The body of the request will be the file you are uploading. Set the `Content-Type` http header to the appropriate mimetype for your file when uploading.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/doi'
      - $ref: '#/components/parameters/filename'
      requestBody:
        description: A binary file with `Content-Type` set.
        required: true
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: File was created on the server.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/file'
                - properties:
                    url:
                      type: string
              examples:
                success:
                  $ref: api/v2/docs/examples/upload_file.json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: putDatasetsByDoiFilesByFilename
      x-operation-id-source: derived
  /datasets/{doi}/urls:
    post:
      summary: Stage a file submission by URL
      tags:
      - Files
      description: 'The URL you specify will be deposited into the storage repository from a publicly accessible URL on the internet when the in-progress dataset is submitted. The dataset must be an in-progress dataset. The URL will be validated and metadata about it obtained to populate metadata about the file when it is added. Send the url to be retrieved as part of a JSON document like **{''url'': ''http://example.org/testing/my/file.csv'' }**. Priviliged users may have additional options to specify URL metadata rather than having live-validation and metadata gathering performed from the Internet.'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/doi'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/url_json'
      responses:
        '201':
          description: Metadata for the URL was saved and the response JSON indicates information populated for a file object based on the URL.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/file'
                - properties:
                    url:
                      type: string
              examples:
                success:
                  $ref: api/v2/docs/examples/upload_file.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postDatasetsByDoiUrls
      x-operation-id-source: derived
components:
  schemas:
    hal_self_link:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/hal_link'
    file:
      allOf:
      - $ref: '#/components/schemas/file_links'
      - properties:
          path:
            type: string
          size:
            type: integer
          mimeType:
            type: string
          status:
            type: string
          digest:
            type: string
          digestType:
            type: string
          description:
            type: string
    hal_link:
      type: object
      properties:
        href:
          type: string
          format: uri
      required:
      - href
    url_json:
      type: object
      properties:
        url:
          type: string
      required:
      - url
    hal_curie:
      type: object
      properties:
        name:
          type: string
        href:
          type: string
          format: uri
        templated:
          type: boolean
      required:
      - name
      - href
      - templated
    Error:
      type: object
      properties:
        error:
          type: string
    hal_file_links:
      properties:
        stash:dataset:
          $ref: '#/components/schemas/hal_link'
        stash:version:
          $ref: '#/components/schemas/hal_link'
        stash:files:
          $ref: '#/components/schemas/hal_link'
        stash:download:
          $ref: '#/components/schemas/hal_link'
        curies:
          type: array
          items:
            $ref: '#/components/schemas/hal_curie'
    file_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_file_links'
  parameters:
    doi:
      in: path
      name: doi
      schema:
        type: string
      required: true
      description: 'DOI like doi:10.1000/18238577 that should be URL encoded (example: <code>doi%3A10.1000%2F18238577</code>)'
    filename:
      in: path
      name: id
      schema:
        type: string
      required: true
      description: The filename is the filename for the file. It should be escaped in the URL (for example 'cat tundra.jpg' would be 'cat%20tundra.jpg'.  Your programming language will have a library to encode for you.
    file_id:
      in: path
      name: id
      schema:
        type: integer
      required: true
      description: The file ID is a unique integer and can be obtained from the list of files for a version of a dataset.
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
    Unacceptable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: '406 - unacceptable: please set your `Content-Type` or `Accept` headers for application/json. `Accept` header is optional if you are using `Content-Type: application/json`.'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized, must have current bearer token.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT