api.raml

#%RAML 1.0 Extension

extends: https://raw.githubusercontent.com/VEuPathDB/docs-api-schema/v2.0.2/libraries/base-service.raml

title: EDA Workspace Data Service API
version: v1.0.0
mediaType: application/json

uses:
  error: https://raw.githubusercontent.com/VEuPathDB/docs-api-schema/v2.0.2/libraries/errors.raml
  lib: schema/library.raml

annotationTypes:
  className:
    type: string

securitySchemes:
  header-auth:
    description: Authentication based on a WDK auth cookie.
    type:
      x-custom
    describedBy:
      headers:
        Auth_Key:
          description: Authorization header.
          type: string

# # # # # # # # # # # # # # # # # # #
#                                   #
# Subsetting Endpoints              #
#                                   #
# # # # # # # # # # # # # # # # # # #

/clear-metadata-cache:
  displayName: Clears the metadata cache; useful if new data has been loaded into the database
  get:
    responses:
      200:
        body:
          text/plain:

/studies:
  displayName: Overview of available studies
  get:
    responses:
      200:
        body:
          application/json:
            type: lib.StudiesGetResponse

  /{study-id}:
    uriParameters:
      study-id:
        description: ID of the study of interest
        type: string
    get:
      responses:
        200:
          body:
            application/json:
              type: lib.StudyIdGetResponse

    /entities:

      /{entity-id}:
        uriParameters:
          entity-id:
            description: ID of the entity of interest
            type: string
        get:
          description: Returns entity details, not including its children (which it may or may not have; see study endpoint)
          responses:
            200:
              body:
                application/json:
                  type: lib.EntityIdGetResponse

        /count:
          post:
            securedBy: header-auth
            description: |
              Return a count of entities in this subset.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
            body:
              application/json:
                type: lib.EntityCountPostRequest
            responses:
              200:
                body:
                  application/json:
                    type: lib.EntityCountPostResponse

        /tabular:
          post:
            securedBy: header-auth
            description: |
              Return a tabular report of one or more variables belonging to this entity.  The output will also include all ancestor primary keys.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
            body:
              application/json:
                type: lib.EntityTabularPostRequest
              application/x-www-form-urlencoded:
            responses:
              200:
                body:
                  text/tab-separated-values:
                    type: lib.EntityTabularPostResponse
                  application/json:
                    type: lib.EntityTabularPostResponse

        /variables:

          /{variable-id}:

            /root-vocab:
              description: |
                Groups values of this variable by their rows' root entity ID (collecting a vocabulary of values specific
                to each root entity record) and returns them as a tabular result where each row is a distinct 
                combination of root entity ID and variable value. This is useful for reducing applicable vocabularies 
                of this variable to only the root entities remaining after a subset operation.
              post:
                securedBy: header-auth
                body:
                  application/json:
                    type: lib.VocabByRootEntityPostRequest
                responses:
                  200:
                    body:
                      text/tab-separated-values:
                        type: lib.VocabByRootEntityPostResponse

            /distribution:
              post:
                securedBy: header-auth
                description: |
                  Return the count of entities in the subset that have a value for this variable, and |
                  a distribution for this variable, i.e., entity counts for each value of this |
                  variable.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
                body:
                  application/json:
                    type: lib.VariableDistributionPostRequest
                responses:
                  200:
                    body:
                      application/json:
                        type: lib.VariableDistributionPostResponse

/ss-internal/studies/{study-id}/entities/{entity-id}:

  /count:
    post:
      securedBy: header-auth
      description: |
        Return a count of entities in this subset.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
      body:
        application/json:
          type: lib.EntityCountPostRequest
      responses:
        200:
          body:
            application/json:
              type: lib.EntityCountPostResponse

  /tabular:
    post:
      securedBy: header-auth
      description: |
        Return a tabular report of one or more variables belonging to this entity.  The output will also include all ancestor primary keys.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
      body:
        application/json:
          type: lib.EntityTabularPostRequest
      responses:
        200:
          body:
            text/tab-separated-values:
              type: lib.EntityTabularPostResponse
            application/json:
              type: lib.EntityTabularPostResponse

  /variables/{variable-id}/distribution:
    post:
      securedBy: header-auth
      description: |
        Return the count of entities in the subset that have a value for this variable, and |
        a distribution for this variable, i.e., entity counts for each value of this |
        variable.  In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
      body:
        application/json:
          type: lib.VariableDistributionPostRequest
      responses:
        200:
          body:
            application/json:
              type: lib.VariableDistributionPostResponse

# # # # # # # # # # # # # # # # # # #
#                                   #
# Merging Service Endpoints         #
#                                   #
# # # # # # # # # # # # # # # # # # #

/merging:
  /derived-variables:
    /input-specs:
      displayName: This endpoint is used only to produce documentation of derived variable configuration types
      post:
        body:
          application/json:
            type: lib.DerivedVariableDocumentationRequest
        responses:
          204:

    /metadata:
      /variables:
        displayName: Return metadata about a small collection of derived variables
        post:
          body:
            application/json:
              type: lib.DerivedVariableBulkMetadataRequest
          responses:
            200:
              body:
                application/json:
                  type: lib.DerivedVariableMetadata[]
      /units:
        displayName: Return metadata about available unit conversions
        get:
          responses:
            200:
              body:
                application/json:
                  type: lib.UnitConversionMetadataResponse

  /query:
    displayName: Merged Tabular Data Query
    post:
      securedBy: header-auth
      body:
        application/json:
          type: lib.MergedEntityTabularPostRequest
      responses:
        200:
          body:
            text/tab-separated-values:
              type: lib.EntityTabularPostResponse
        400:
          body:
            application/json:
              type: error.BadRequestError
        422:
          body:
            application/json:
              type: error.UnprocessableEntityError
        500:
          body:
            application/json:
              type: error.ServerError

# # # # # # # # # # # # # # # # # # #
#                                   #
# Merging Internal Endpoints        #
#                                   #
# # # # # # # # # # # # # # # # # # #

/merging-internal:

  /derived-variables:
    /metadata:
      /variables:
        displayName: Return metadata about a small collection of derived variables
        post:
          body:
            application/json:
              type: lib.DerivedVariableBulkMetadataRequest
          responses:
            200:
              body:
                application/json:
                  type: lib.DerivedVariableMetadata[]

  /query:
    displayName: Merged Tabular Data Query
    post:
      securedBy: header-auth
      body:
        application/json:
          type: lib.MergedEntityTabularPostRequest
      responses:
        200:
          body:
            text/tab-separated-values:
              type: lib.EntityTabularPostResponse
        400:
          body:
            application/json:
              type: error.BadRequestError
        422:
          body:
            application/json:
              type: error.UnprocessableEntityError
        500:
          body:
            application/json:
              type: error.ServerError

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#                                                                           #
#  Compute Service                                                          #
#                                                                           #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

#
# Top-level endpoint returns list of compute options and serves as a parent to plugin endpoints
#
/computes:
  displayName: Available Plugins
  get:
    responses:
      200:
        body:
          application/json:
            type: array
            items:
              type: lib.PluginOverview

  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
  #                                                                           #
  #  Begin Plugin Endpoint Definitions                                        #
  #                                                                           #
  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

  /example:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.ExamplePluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /{file}:
      uriParameters:
        file:
          type: string
          description: MUST be one of "meta", "tabular", "statistics".
      post:
        body:
          application/json: lib.ExamplePluginRequest
        responses:
          200:
            body:
              text/plain: any


  /betadiv:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.BetaDivPluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /{file}:
      uriParameters:
        file:
          type: string
          description: MUST be one of "meta", "tabular", "statistics".
      post:
        body:
          application/json: lib.BetaDivPluginRequest
        responses:
          200:
            body:
              text/plain: any

  /alphadiv:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.AlphaDivPluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /{file}:
      uriParameters:
        file:
          type: string
          description: MUST be one of "meta", "tabular", "statistics".
      post:
        body:
          application/json: lib.AlphaDivPluginRequest
        responses:
          200:
            body:
              text/plain: any

  /rankedabundance:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.RankedAbundancePluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /{file}:
      uriParameters:
        file:
          type: string
          description: MUST be one of "meta", "tabular", "statistics".
      post:
        body:
          application/json: lib.RankedAbundancePluginRequest
        responses:
          200:
            body:
              text/plain: any

  /differentialabundance:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.DifferentialAbundancePluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /statistics:
      post:
        body:
          application/json: lib.DifferentialAbundancePluginRequest
        responses:
          200:
            body:
              application/json: lib.DifferentialAbundanceStatsResponse

  /differentialexpression:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.DifferentialExpressionPluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /statistics:
      post:
        body:
          application/json: lib.DifferentialExpressionPluginRequest
        responses:
          200:
            body:
              application/json: lib.DifferentialExpressionStatsResponse


  /correlation:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.CorrelationPluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /statistics:
      post:
        body:
          application/json: lib.CorrelationPluginRequest
        responses:
          200:
            body:
              application/json: lib.CorrelationStatsResponse

  /selfcorrelation:
    post:
      queryParameters:
        autostart:
          type: boolean
          required: false
          default: true
      body:
        application/json: lib.SelfCorrelationPluginRequest
      responses:
        200:
          body:
            application/json: lib.JobResponse
    /statistics:
      post:
        body:
          application/json: lib.SelfCorrelationPluginRequest
        responses:
          200:
            body:
              application/json: lib.CorrelationStatsResponse

  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
  #                                                                           #
  #  End Plugin Endpoint Definitions                                          #
  #                                                                           #
  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

/admin:
  (className): AdminRPC
  /compute:
    /list-possible-dead-workspaces:
      get:
        description: |-
          Returns a list of job IDs for compute jobs whose workspaces are in a
          state where the jobs appear to be running, however no record of them
          is present in the local postgres database.
          
          **NOTE**: A job ID appearing in this list _DOES NOT_ mean that they
          are actually dead.  Jobs that are actively being run by another campus
          will also appear in this list.
          
          This list may be used as a starting point in the process of locating
          dead workspaces.
        responses:
          200:
            body:
              text/plain:
                type: any

    /workspaces:
      /{job-id}:
        uriParameters:
          job-id:
            type: string
            minLength: 32
            maxLength: 32
            pattern: '^[\dA-Fa-f]{32}$'
        delete:
          description: |-
            Deletes the contents of a workspace by force.  The target workspace
            need not be valid for this operation.
          responses:
            204:


/expire-compute-jobs:
  get:
    description: Expire jobs based on criteria
    queryParameters:
      job-id:
        type: string
      study-id:
        type: string
      plugin-name:
        type: string
      admin-auth-token:
        type: string
    responses:
      200:
        body:
          application/json:
            type: lib.ExpiredJobsResponse

/internal-jobs:
  get:
    responses:
      200:
        body:
          application/json:
            type: lib.InternalJob[]

  /{job-id}:
    uriParameters:
      job-id:
        type: string
        minLength: 32
        maxLength: 32
        pattern: '^[\dA-Fa-f]{32}$'
    get:
      responses:
        200:
          description: |
            Success
            
            The target job exists and its status returned.
          body:
            application/json:
              type: lib.InternalJob

/jobs:
  /{job-id}:
    uriParameters:
      job-id:
        type: string
        minLength: 32
        maxLength: 32
        pattern: '^[\dA-Fa-f]{32}$'
    delete:
      description: Deletes a target job by ID
      responses:
        204:
          description: Success
        404:
          description: Not Found
          body:
            application/json:
              type: error.NotFoundError
        500:
          description: Server Error
          body:
            application/json:
              type: error.ServerError
    get:
      description: Gets the status of the target job.
      responses:
        200:
          description: |
            Success
            
            The target job exists and its status returned.
          body:
            application/json:
              type: lib.JobResponse
              examples:
                queued:
                  strict: true
                  value:
                    jobID: 9ab9a5886d6abb9ebc82a40f770a1db3
                    status: queued
                    queuePosition: 3
                in-progress:
                  strict: true
                  value:
                    jobID: 9ab9a5886d6abb9ebc82a40f770a1db3
                    status: in-progress
                complete:
                  strict: true
                  value:
                    jobID: 9ab9a5886d6abb9ebc82a40f770a1db3
                    status: complete
                failed:
                  strict: true
                  value:
                    jobID: 9ab9a5886d6abb9ebc82a40f770a1db3
                    status: failed
                expired:
                  strict: true
                  value:
                    jobID: 9ab9a5886d6abb9ebc82a40f770a1db3
                    status: expired
        404:
          description: |
            Not Found
            
            The target `{job-id}` was not found.
          body:
            application/json:
              type: error.NotFoundError
        500:
          description: |
            Internal Server Error
            
            An unexpected exception was thrown while attempting to process
            the request.
          body:
            application/json:
              type: error.ServerError
    /files:
      get:
        description: |
          Lists the files available for a completed job.
        responses:
          200:
            description: |
              Success
              
              The job has completed and has files available.
            body:
              application/json:
                type: string[]
                example:
                  - output
          403:
            description: |
              Forbidden
              
              The job has not yet completed and thus cannot yet be queried for
              files.
            body:
              application/json:
                type: error.ForbiddenError
          404:
            description: |
              Not Found
              
              The target `{job-id}` was not found.
            body:
              application/json:
                type: error.NotFoundError
          500:
            description: |
              Internal Server Error
              
              An unexpected exception was thrown while attempting to process
              the request.
            body:
              application/json:
                type: error.ServerError
      /{file-name}:
        uriParameters:
          file-name:
            type: string
            minLength: 1
        get:
          description: |
            Returns the target file from a completed job.
          responses:
            200:
              description: |
                Success
                
                The job has completed and the target file exists to return.
              headers:
                Content-Disposition:
                  type: string
                  example:
                    value: attachment; filename=output.txt
              body:
                text/plain:
                  type: any
                  example: dlrow olleh
            403:
              description: |
                Forbidden
                
                The job has not yet completed and thus cannot yet be queried for
                files.
              body:
                application/json:
                  type: error.ForbiddenError
            404:
              description: |
                Not Found
                
                Either the target `{job-id}` was not found or no file with the
                name `{file-name}` exists.
              body:
                application/json:
                  type: error.NotFoundError
            500:
              description: |
                Internal Server Error
                
                An unexpected exception was thrown while attempting to process
                the request.
              body:
                application/json:
                  type: error.ServerError

# # # # # # # # # # # # # # # # # # #
#                                   #
# Data Service Specific Endpoints   #
#                                   #
# # # # # # # # # # # # # # # # # # #

/filter-aware-metadata/continuous-variable:
  post:
    description: Returns equal interval, quantile and standard deviation based bin ranges and/or the median for a continuous variable over a specified range.
    body:
      application/json:
        type: lib.ContinuousVariableMetadataPostRequest
    responses:
      200:
        body:
          application/json:
            type: lib.ContinuousVariableMetadataPostResponse

/apps:
  displayName: Available Apps
  get:
    responses:
      200:
        body:
          application/json:
            type: lib.AppsGetResponse

  /standalone-map/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /map-markers:
      post:
        description: Returns data required to make Standalone Map markers
        body:
          application/json:
            type: lib.StandaloneMapMarkersPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.StandaloneMapMarkersPostResponse

      /bubbles:
        post:
          description: |
            Returns data required to make bubble markers.
          body:
            application/json:
              type: lib.StandaloneMapBubblesPostRequest
          responses:
            200:
              body:
                application/json:
                  type: lib.StandaloneMapBubblesPostResponse

        /legend:
          post:
            description: Returns data required to make bubble marker legends
            body:
              application/json:
                type: lib.StandaloneMapBubblesLegendPostRequest
            responses:
              200:
                body:
                  application/json:
                    type: lib.StandaloneMapBubblesLegendPostResponse
      /collections:
        post:
          description: |
            Map marker endpoint for collection variables.
          body:
            application/json:
              type: lib.StandaloneCollectionMapMarkerPostRequest
          responses:
            200:
              body:
                application/json:
                  type: lib.StandaloneCollectionMapMarkerPostResponse


  /standalone-map-xyrelationships/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /scatterplot:
      post:
        description: Returns data required to create a floating scatterplot visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingScatterplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingScatterplotPostResponse

    /lineplot:
      post:
        description: Returns data required to create a floating lineplot visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingLineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingLineplotPostResponse

    /timeseries:
      post:
        description: Returns data required to create a floating time series visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingLineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingLineplotPostResponse

  /standalone-map-distributions/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /histogram:
      post:
        description: Returns data required to create a floating histogram visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingHistogramPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingHistogramPostResponse

    /timeline:
      post:
        description: Returns data required to create a floating histogram visualization for date variables only in the Standalone Map
        body:
          application/json:
            type: lib.FloatingHistogramPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingHistogramPostResponse

    /boxplot:
      post:
        description: Returns data required to create a floating boxplot visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingBoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingBoxplotPostResponse

  /standalone-map-countsandproportions/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /barplot:
      post:
        description: Returns data required to create a floating bar plot visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingBarplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingBarplotPostResponse

    /conttable:
      post:
        description: Returns data required to create a floating RxC mosaic plot visualization in the Standalone Map
        body:
          application/json:
            type: lib.FloatingContTablePostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingContTablePostResponse

  /standalone-map-continuous-collections/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /lineplot:
      post:
        description: Returns data required to create a floating line plot visualization for continuous variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingLineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingLineplotPostResponse

    /timeseries:
      post:
        description: Returns data required to create a floating time series visualization for continuous variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingLineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingLineplotPostResponse

    /boxplot:
      post:
        description: Returns data required to create a floating box plot visualization for continuous variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingBoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingBoxplotPostResponse

    /histogram:
      post:
        description: Returns data required to create a floating histogram visualization for continuous variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingHistogramPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingHistogramPostResponse

  /standalone-map-categorical-collections/visualizations:
    displayName: Available visualizations for the Standalone Map application

    /lineplot:
      post:
        description: Returns data required to create a floating line plot visualization for categorical variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingLineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingLineplotPostResponse


    /barplot:
      post:
        description: Returns data required to create a floating bar plot visualization for categorical variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingBarplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingBarplotPostResponse

    /conttable:
      post:
        description: Returns data required to create a floating RxC mosaic plot visualization for categorical variable collections in the Standalone Map
        body:
          application/json:
            type: lib.CollectionFloatingContTablePostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.FloatingContTablePostResponse

  /pass/visualizations:
    displayName: Available visualizations for the null/ pass-through app

    /map-markers:
      post:
        description: Returns data required to make MapVeu markers <br> Java impl- working <br> R impl- NA
        body:
          application/json:
            type: lib.MapPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.MapPostResponse

    /table:
      post:
        description: Return a tabular report of one or more variables. In the request, `filters` must be a subclass of [Filter](#type:lib.Filter)
        body:
          application/json:
            type: lib.TablePostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.TablePostResponse

    /scatterplot:
      post:
        description: Returns data required to create a scatterplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.ScatterplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ScatterplotPostResponse


    /densityplot:
      post:
        description: Returns data required to create a densityplot visualization <br> Java impl- NA <br> R impl- drafted, passing unit tests, not confirmed working
        body:
          application/json:
            type: lib.DensityplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.DensityplotPostResponse

    /timeseries:
      post:
        description: Returns data required to create a Time Series visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.LineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.LineplotPostResponse

    /lineplot:
      post:
        description: Returns data required to create a lineplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.LineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.LineplotPostResponse

    /histogram:
      post:
        description: Returns data required to create a histogram visualization. <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.HistogramPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.HistogramPostResponse

    /boxplot:
      post:
        description: Returns data required to create a boxplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.BoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BoxplotPostResponse

    /heatmap:
      post:
        description: Returns data required to create a heatmap visualization <br> Java impl- NA <br> R impl- drafted
        body:
          application/json:
            type: lib.HeatmapPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.HeatmapPostResponse

    /barplot:
      post:
        description: Returns data required to create a bar plot visualization <br> Java impl- drafted, not working <br> R impl- working
        body:
          application/json:
            type: lib.BarplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BarplotPostResponse

    /map-markers-overlay:
      post:
        description: Returns data required to create a pie plot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.MapMarkersOverlayPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.MapMarkersOverlayPostResponse

    /twobytwo:
      post:
        description: Returns data required to create a mosaic plot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.TwoByTwoPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.TwoByTwoPostResponse

    /conttable:
      post:
        description: Returns data required to create a mosaic plot visualization <br> Java impl- NA <br> R impl- drafted
        body:
          application/json:
            type: lib.MosaicPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ContTablePostResponse

  /alphadiv/visualizations:
    displayName: Visualizations for assessing internal sample diversity (alpha diversity).

    /boxplot:
      post:
        description: Returns data required to create a box plot with alpha diversity as dependent axis <br> Java impl- NA <br> R impl- NA
        body:
          application/json:
            type: lib.AlphaDivBoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BoxplotPostResponse

    /scatterplot:
        post:
          description: Returns data required to create a scatterplot that explores the relationship between a continuous variable and alpha diversity <br> Java impl- NA <br> R impl- NA
          body:
            application/json:
              type: lib.AlphaDivScatterplotPostRequest
          responses:
            200:
              body:
                application/json:
                  type: lib.ScatterplotPostResponse

  /abundance/visualizations:
    displayName: Visualizations for assessing abundance data in a collection of samples.

    /boxplot:
      post:
        description: Returns data required to create a box plot with abundance as dependent axis <br> Java impl- NA <br> R impl- NA
        body:
          application/json:
            type: lib.AbundanceBoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BoxplotPostResponse

    /scatterplot:
      post:
        description: Returns data required to create a scatterplot that explores the relationship between a continuous variable and alpha diversity <br> Java impl- NA <br> R impl- NA
        body:
          application/json:
            type: lib.AbundanceScatterplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ScatterplotPostResponse

  /betadiv/visualizations:
    displayName: Visualizations for exploring the diversity between samples (beta diversity).

    /scatterplot:
      post:
        description: Returns data required to create a scatterplot that explores the differences between samples in a dataset as described by beta diversity <br> Java impl- NA <br> R impl- NA
        body:
          application/json:
            type: lib.BetaDivScatterplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ScatterplotPostResponse

  /differentialabundance/visualizations:
    displayName: Visualizations for interrogating differentially abundant taxa, genes, or pathways

    /volcanoplot:
      post:
        description: Returns data required to create a volcanoplot from a differential abundance analysis.
        body:
          application/json:
            type: lib.DifferentialAbundanceVolcanoplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.DifferentialAbundanceStatsResponse

  /differentialexpression/visualizations:
    displayName: Visualizations for interrogating differentially expressed genes

    /volcanoplot:
      post:
        description: Returns data required to create a volcanoplot from a differential expression analysis.
        body:
          application/json:
            type: lib.DifferentialExpressionVolcanoplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.DifferentialExpressionStatsResponse

  /correlation/visualizations:
    displayName: Visualizations for discovering correlations between various assay data

    /bipartitenetwork:
      post:
        description: Returns data required to create a bipartite network from a correlation matrix.
        body:
          application/json:
            type: lib.CorrelationBipartitenetworkPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.CorrelationBipartiteNetworkPostResponse

  /correlationassayassay/visualizations:
    displayName: Visualizations for discovering corrleations between various assay data

    /bipartitenetwork:
      post:
        description: Returns data required to create a bipartite network from a correlation matrix.
        body:
          application/json:
            type: lib.CorrelationAssayAssayBipartitenetworkPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.CorrelationBipartiteNetworkPostResponse

  /selfcorrelation/visualizations:
    displayName: Visualizations for discovering correlations between variables within an assay

    /unipartitenetwork:
      post:
        description: Returns data required to create a unipartite network from a correlation matrix.
        body:
          application/json:
            type: lib.SelfCorrelationUnipartitenetworkPostRequest
        responses:
          200:
            body:

  /correlationassaymetadata/visualizations:
    displayName: Visualizations for discovering corrleations between assay data and sample metadata

    /bipartitenetwork:
      post:
        description: Returns data required to create a bipartite network from a correlation matrix.
        body:
          application/json:
            type: lib.CorrelationAssayMetadataBipartitenetworkPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BipartiteNetworkPostResponse

  /distributions/visualizations:
    displayName: Visualizations for exploring distributions of data.

    /histogram:
      post:
        description: Returns data required to create a histogram visualization. <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.HistogramPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.HistogramPostResponse

    /boxplot:
      post:
        description: Returns data required to create a boxplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.BoxplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BoxplotPostResponse

  /countsandproportions/visualizations:
    displayName: Visualizations for exploring quantities and relative sizes of data.

    /barplot:
      post:
        description: Returns data required to create a bar or pie plot visualization <br> Java impl- drafted, not working <br> R impl- working
        body:
          application/json:
            type: lib.BarplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.BarplotPostResponse

    /twobytwo:
      post:
        description: Returns data required to create a mosaic plot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.TwoByTwoPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.TwoByTwoPostResponse

    /conttable:
      post:
        description: Returns data required to create a mosaic plot visualization <br> Java impl- NA <br> R impl- drafted
        body:
          application/json:
            type: lib.MosaicPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ContTablePostResponse

  /xyrelationships/visualizations:
    displayName: Visualizations for exploring relationships between two continuous variables.

    /scatterplot:
      post:
        description: Returns data required to create a scatterplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.ScatterplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ScatterplotPostResponse

    /lineplot:
      post:
        description: Returns data required to create a lineplot visualization <br> Java impl- NA <br> R impl- working
        body:
          application/json:
            type: lib.LineplotPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.LineplotPostResponse

  /sample/visualizations:
    displayName: Sample visualizations demonstrating/testing service capabilities

    /record-count:
      post:
        description: Returns a count of the records in the subset
        body:
          application/json:
            type: lib.RecordCountPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.RecordCountPostResponse

    /multi-stream:
      post:
        description: Returns a stream of records with its first two attributes (combined from parallel streams)
        body:
          application/json:
            type: lib.MultiStreamPostRequest
        responses:
          200:
            body:
              text/plain:
                type: lib.EntityTabularPostResponse

    /collections-test:
      post:
        description: Returns a tabular response for the subset with all vars in the requested collection
        body:
          application/json:
            type: lib.TestCollectionsPostRequest
        responses:
          200:
            body:
              text/plain:
                type: lib.EntityTabularPostResponse

    /categorical-distribution:
      post:
        description: Returns a set of count and proportion distributions for a native categorical variable
        body:
          application/json:
            type: lib.CategoricalDistributionPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.CategoricalDistributionPostResponse

  /samplewithcompute/visualizations:
    displayName: Sample visualizations with computes demonstrating/testing service capabilities

    /viz-with-compute:
      post:
        description: Sample visualization plugin that uses data from a compute
        body:
          application/json:
            type: lib.ExampleComputeVizPostRequest
        responses:
          200:
            body:
              application/json:
                type: lib.ExampleComputeVizPostResponse

# # # # # # # # # # # # # # # # # # #
#                                   #
# End Data Service Plugins          #
#                                   #
# # # # # # # # # # # # # # # # # # #


# # # # # # # # # # # # # # # # # # #
#                                   #
# Dataset Access Endpoints          #
#                                   #
# # # # # # # # # # # # # # # # # # #
/staff:
  get:
    displayName: Staff List
    description: List dataset staff in ascending order by ID.
    queryParameters:
      limit?:
        type: integer
        format: int64
        minimum: 0
        default: 1000
        description: Number of rows to include in the result
      offset?:
        type: integer
        format: int64
        minimum: 0
        default: 0
        description: Number of rows to skip from the result
    responses:
      200:
        body:
          type: lib.StaffList
  post:
    displayName: New Staff Entry
    description: Create a new dataset staff record.
    body: lib.NewStaffRequest
    responses:
      200:
        body: lib.NewStaffResponse

  /{staff-id}:
    uriParameters:
      staff-id:
        type: lib.DatastoreId
    patch:
      displayName: Update Staff Entry
      description: Update dataset staff.
      body: lib.StaffPatch[]
      responses:
        204:
    delete:
      displayName: Delete Staff Entry
      description: Delete dataset staff.
      responses:
        204:

/dataset-providers:
  get:
    displayName: Provider List
    description: Get a list of providers for this dataset.
    queryParameters:
      datasetId:
        type: string
        required: true
      limit?:
        type: integer
        format: int64
        minimum: 0
        default: 1000
        description: Number of rows to include in the result
      offset?:
        type: integer
        format: int64
        minimum: 0
        default: 0
        description: Number of rows to skip from the result
    responses:
      200:
        body: lib.DatasetProviderList

  post:
    displayName: New Provider
    description: Create a new dataset provider record.
    body: lib.DatasetProviderCreateRequest
    responses:
      200:
        body: lib.DatasetProviderCreateResponse

  /{provider-id}:
    uriParameters:
      provider-id:
        description: Dataset provider ID.
        type: lib.DatastoreId
    patch:
      displayName: Update Provider
      description: Update a dataset provider record.
      body: lib.DatasetProviderPatch[]
      responses:
        204:
    delete:
      displayName: Delete Provider
      description: Delete a dataset provider record.
      responses:
        204:

/dataset-end-users:
  get:
    displayName: List End Users
    description: Get a list of all end-users for the specified dataset.
    queryParameters:
      datasetId:
        displayName: Dataset ID
        type: string
      limit?:
        displayName: Result Limit
        description: Number of rows to include in the result
        type: integer
        format: int64
        minimum: 0
        default: 100
      offset?:
        displayName: Result Offset
        description: Number of rows to skip from the result
        type: integer
        format: int64
        minimum: 0
        default: 0
      approval?:
        displayName: Approval Status
        description: Filter results by the approval status of the users.
        type: lib.ApprovalStatus
    responses:
      200:
        body: lib.EndUserList
  post:
    displayName: New End User
    description: Create a new dataset end-user record.
    body: lib.EndUserCreateRequest
    responses:
      200:
        body: lib.EndUserCreateResponse

  /{end-user-id}:
    uriParameters:
      end-user-id:
        description: |
          ID of a specific end-user record.  This ID consists of the WDK user ID
          for the user followed by a single dash (`-`) character followed by
          the dataset ID. Example: `82-DS_897fe55e6f`.
        type: string
        pattern: "^\\d+-\\w+$"
    get:
      displayName: End User Details
      description: Get the details of an end-user record.
      responses:
        200:
          body: lib.EndUser
    delete:
      displayName: Delete End User
      description: Delete an end user access grant.
      responses:
        204:
          description: Success
    patch:
      displayName: Update End User
      description: |
        Update an end user record.

        The following rules apply to end user self updates:

        1. The user may only submit updates while their access request is in the
           "requested" status.
        2. Only the following fields may be updated:
            1. `purpose`
            2. `researchQuestion`
            3. `analysisPlan`
            4. `disseminationPlan`

        This endpoint supports only the listed JSON Patch operations on the
        listed paths.  All other JSON paths or operations will result in a 403
        error.

        **`/startDate`**

        * `add`
        * `remove`
        * `replace`

        This field may only be altered by site owners and dataset managers.

        **`/duration`**

        * `add`
        * `remove`
        * `replace`

        This field may only be altered by site owners and dataset managers.

        **`/restrictionLevel`**

        * `replace`

        This field may only be altered by site owners and dataset managers.

        **`/purpose`**

        * `replace`

        Type: `string`

        This field may be altered by site owners and dataset managers at any
        time.

        This field may only be altered by end users while their access request
        is in the "requested" status.

        **`/researchQuestion`**

        * `replace`

        Type: `string`

        This field may be altered by site owners and dataset managers at any
        time.

        This field may only be altered by end users while their access request
        is in the "requested" status.

        **`/analysisPlan`**

        * `replace`

        Type: `string`

        This field may be altered by site owners and dataset managers at any
        time.

        This field may only be altered by end users while their access request
        is in the "requested" status.

        **`/disseminationPlan`**

        * `replace`

        Type: `string`

        This field may be altered by site owners and dataset managers at any
        time.

        This field may only be altered by end users while their access request
        is in the "requested" status.

        **`priorAuth`**

        * `replace`

        Type: `string`

        This field may be altered by site owners and dataset managers at any
        time.

        This field may only be altered by end users while their access request
        is in the "requested" status.

        **`/approvalStatus`**

        * `replace`

        This field may only be altered by site owners and dataset managers.

        **`/denialReason`**

        * `add`
        * `remove`
        * `replace`

        This field may only be altered by site owners and dataset managers.
      body: lib.EndUserPatch[]
      responses:
        204:

/permissions:
  get:
    responses:
      200:
        body: lib.PermissionsGetResponse

  /{dataset-id}:
    get:
      responses:
        200:
          body: lib.StudyPermissionInfo

/history:
  get:
    queryParameters:
      limit:
        type: integer
        format: int64
        minimum: 1
        maximum: 999
        default: 999
      offset:
        type: integer
        format: int64
        minimum: 0
        default: 0
    responses:
      200:
        body: lib.HistoryResponse

/approve-eligible-access-requests:
  post:
    description: Approve protected study requests in which auto-approval duration has elapsed
    responses:
      204:
        description: Success

# # # # # # # # # # # # # # # # # # #
#                                   #
# Dataset Download Endpoints        #
#                                   #
# # # # # # # # # # # # # # # # # # #
/download:
  /{project}:
    /{study-id}:
      displayName: Get release listing for this study ID
      get:
        responses:
          200:
            body:
              application/json:
                type: string[]

      /{release}:
        displayName: Get file listing for this release
        get:
          responses:
            200:
              body:
                application/json:
                  type: lib.File[]

        /{file}:
          displayName: Download a single file
          securedBy: header-auth
          get:
            responses:
              200:
                body:
                  text/plain:
                    type: lib.FileContentResponse

# # # # # # # # # # # # # # # # # # #
#                                   #
# User Service Endpoints            #
#                                   #
# # # # # # # # # # # # # # # # # # #
/public/analyses/{project-id}:
  displayName: Provide a list of public analyses
  get:
    responses:
      200:
        body:
          application/json:
            type: lib.AnalysisSummaryWithUser[]

# Note this is identical to the analyses/{id}/copy endpoint without the user validation
/import-analysis/{project-id}:

  /{analysis-id}:
    displayName: Copy an existing analysis
    get:
      responses:
        200:
          body:
            application/json:
              type: lib.AnalysisListPostResponse

    /info:
      displayName: Returns public information about an analysis
      get:
        responses:
          200:
            body:
              application/json:
                type: lib.SingleAnalysisPublicInfo

/metrics/user/{project-id}/analyses:
  displayName: Get usage metrics for EDA users by time period
  get:
    queryParameters:
      startDate:
        description: optional start date (yyyy-mm-dd)
        type: string
      endDate:
        description: optional end date (yyyy-mm-dd)
        type: string
      studyType:
        enum: [ALL, USER, CURATED]
        default: ALL
    responses:
      200:
        body:
          application/json:
            type: lib.UserAnalysisMetricsResponse

  /reports:
    displayName: Download usage metric reports for a given month
    get:
      queryParameters:
        reportMonth:
          description: Required report month (yyyy-mm)
          type: string
      responses:
        200:
          body:
            application/zip:
              type: lib.MetricsReportResponse

/users/{user-id}:

  /preferences/{project-id}:
    displayName: EDA-related user preferences
    get:
      responses:
        200:
          body:
            application/json:
              type: string
    put:
      body:
        application/json:
          type: string
      responses:
        202:

  /analyses/{project-id}:
    displayName: Analyses of a single user
    get:
      responses:
        200:
          body:
            application/json:
              type: lib.AnalysisSummary[]
    post:
      body:
        application/json:
          type: lib.AnalysisListPostRequest
      responses:
        200:
          body:
            application/json:
              type: lib.AnalysisListPostResponse
    patch:
      body:
        application/json:
          type: lib.AnalysisListPatchRequest
      responses:
        202:

    /{analysis-id}:
      displayName: Single analysis
      get:
        responses:
          200:
            body:
              application/json:
                type: lib.AnalysisDetail
      patch:
        body:
          application/json:
            type: lib.SingleAnalysisPatchRequest
        responses:
          202:
      delete:
        responses:
          202:

      /copy:
        displayName: Copy an existing analysis
        post:
          responses:
            200:
              body:
                application/json:
                  type: lib.AnalysisListPostResponse

  /derived-variables/{project-id}:
    uriParameters:
      project-id: string

    displayName: Derived Variables

    get:
      displayName: List Derived Variables
      responses:
        200:
          body:
            application/json:
              type: lib.DerivedVariableGetResponse[]
        401:
        404:
        500:

    post:
      displayName: Create a Derived Variable
      body:
        application/json:
          type: lib.DerivedVariablePostRequest
      responses:
        200:
          body:
            application/json:
              type: lib.DerivedVariablePostResponse
        400:
        401:
        403:
        404:
        422:
        500:

    /{derived-variable-id}:
      uriParameters:
        derived-variable-id: string

      get:
        displayName: Look up a Derived Variable
        responses:
          200:
            body:
              application/json:
                type: lib.DerivedVariableGetResponse
          401:
          404:
          500:

      patch:
        displayName: Update Derived Variable
        body:
          application/json:
            type: lib.DerivedVariablePatchRequest
        responses:
          204:
          401:
          403:
          404:
          422:
          500: