Dryad Versions API

openapi: 3.2.0
info:
  title: Dryad Versions 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: Versions
  description: Operations on individual versions of a dataset
paths:
  /versions/{id}:
    get:
      summary: Show a specific dataset version
      tags:
      - Versions
      description: If you know the dataset version's internal id, you can request its record directly. The /versions endpoint lists the versions of a dataset and their ids.
      parameters:
      - $ref: '#/components/parameters/version_id'
      responses:
        '200':
          description: The requested version of the dataset.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/version'
                - properties:
                    changedFields:
                      type: array
                      items:
                        type: string
              examples:
                success:
                  $ref: api/v2/docs/examples/version.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getVersionsById
      x-operation-id-source: derived
  /versions/{id}/files:
    get:
      summary: List the files and file metadata in this version
      tags:
      - Versions
      description: Returns the list of files and file metadata for a known version of a dataset with the version ID you specify.
      parameters:
      - $ref: '#/components/parameters/version_id'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: A list of the files in the version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files'
              examples:
                success:
                  $ref: api/v2/docs/examples/files.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getVersionsByIdFiles
      x-operation-id-source: derived
  /versions/{id}/download:
    get:
      summary: Get a download package for a dataset version
      tags:
      - Versions
      description: This downloads the zip package of a specified, submitted version of the dataset that is visible to the user (or public).
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/version_id'
      responses:
        '200':
          description: The binary content for a compressed archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: not found
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getVersionsByIdDownload
      x-operation-id-source: derived
components:
  schemas:
    hal_self_link:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/hal_link'
    hal_link:
      type: object
      properties:
        href:
          type: string
          format: uri
      required:
      - href
    relatedWork:
      properties:
        relationship:
          format: string
          enum:
          - article
          - dataset
          - preprint
          - software
          - supplemental_information
          - primary_article
          - data_management_plan
        identifierType:
          type: string
        identifier:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
    version:
      allOf:
      - $ref: '#/components/schemas/version_links'
      - $ref: '#/components/schemas/dc_metadata'
      - properties:
          versionNumber:
            type: integer
          versionStatus:
            type: string
            enum:
            - in_progress
            - processing
            - submitted
            description: Internal processing status of files.
          curationStatus:
            type: string
            enum:
            - In progress
            - Processing
            - Queued for curation
            - Private for Peer Review
            - Awaiting payment
            - Curation
            - Action required
            - Withdrawn
            - Embargoed
            - Published
            description: Status of the submission in the curation workflow.
          versionChanges:
            type: string
            enum:
            - files_changed
            - metadata_changed
          publicationDate:
            type: string
          lastModificationDate:
            type: string
          visibility:
            type: string
            description: Whether or not this version is publicly visible.
    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'
    files:
      allOf:
      - $ref: '#/components/schemas/hal_paged_response'
      - $ref: '#/components/schemas/embedded_files'
    hal_curie:
      type: object
      properties:
        name:
          type: string
        href:
          type: string
          format: uri
        templated:
          type: boolean
      required:
      - name
      - href
      - templated
    geolocationBox:
      properties:
        swLongitude:
          description: The longitude of the southwest corner of the box.
          type: number
        swLatitude:
          description: The latitude of the southwest corner of the box.
          type: number
        neLongitude:
          description: The longitude of the northeast corner of the box.
          type: number
        neLatitude:
          description: The latitude of the northeast corner of the box.
          type: number
    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
    embedded_files:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            stash:files:
              type: array
              items:
                $ref: '#/components/schemas/file'
    hal_paged_response:
      allOf:
      - properties:
          _links:
            allOf:
            - $ref: '#/components/schemas/hal_self_link'
            - $ref: '#/components/schemas/hal_page_links'
      - $ref: '#/components/schemas/paging_counts'
    dc_metadata:
      type: object
      properties:
        title:
          type: string
        authors:
          type: array
          items:
            $ref: '#/components/schemas/author'
        abstract:
          type: string
          description: An abstract introducing the dataset.
        funders:
          type: array
          items:
            $ref: '#/components/schemas/funder'
        keywords:
          type: array
          items:
            type: string
        fieldOfScience:
          type: string
          description: A term from the FOS (Fields of Science and Technology) controlled vocabulary. The main category of the dataset.
        hsiStatement:
          type: string
          description: A statement explaining the de-identification of any human subject data in the dataset.
        methods:
          type: string
          description: The methods by which the data was produced. Not required for publication.
        usageNotes:
          type: string
          description: Usage notes for the dataset (Deprecated; It is preferred for this content to appear in the README file for the dataset). If the dataset has been retracted, the retraction statement will appear here.
        locations:
          type: array
          items:
            $ref: '#/components/schemas/geolocation'
        relatedWorks:
          type: array
          items:
            $ref: '#/components/schemas/relatedWork'
      required:
      - title
      - authors
      - abstract
    file_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_file_links'
    funder:
      properties:
        organization:
          type: string
        identifier:
          type: string
          description: The organization identifier, for example a ROR ID.
          example: https://ror.org/00x6h5n95
        identifierType:
          description: Type of identifier — ror, isni, grid, crossref_funder_id or other.
          type: string
          example: ror
        awardNumber:
          type: string
        awardDescription:
          description: Usually used for the program or the division of the award.
          type: string
        order:
          type: integer
    hal_page_links:
      properties:
        first:
          $ref: '#/components/schemas/hal_link'
        last:
          $ref: '#/components/schemas/hal_link'
        prev:
          $ref: '#/components/schemas/hal_link'
        next:
          $ref: '#/components/schemas/hal_link'
    geolocationPoint:
      type: object
      properties:
        latitude:
          description: The latitude of the point.
          type: number
        longitude:
          description: The longitude of the point.
          type: number
    hal_version_links:
      properties:
        stash:dataset:
          $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'
    version_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_version_links'
    author:
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        affiliation:
          type: string
        affiliationROR:
          type: string
          description: Preferred identifier for the author affiliation.
        affiliations:
          type: array
          items:
            name: string
            ror_id: string
        affiliationISNI:
          type: string
        orcid:
          type: string
        order:
          type: integer
    paging_counts:
      properties:
        count:
          type: integer
        total:
          type: integer
    geolocation:
      properties:
        place:
          description: A place name.
          type: string
        box:
          $ref: '#/components/schemas/geolocationBox'
          description: A bounding box.
        point:
          $ref: '#/components/schemas/geolocationPoint'
          description: A coordinate point.
  parameters:
    version_id:
      in: path
      name: id
      schema:
        type: integer
      required: true
      description: The version ID is a unique integer and can be obtained from the list of versions for a dataset.
    per_page:
      in: query
      name: per_page
      schema:
        type: integer
      description: Number of results to return on each page. Defaults to 20. Maximum allowed is 100.
    page:
      in: query
      name: page
      schema:
        type: integer
      description: Which page of results to view. Defaults to page 1.
  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