negotiator.yaml

openapi: 3.0.3
info:
  version: 3.0.1
  title: BBMRI-ERIC Negotiator
  description: >-
    BBMRI-ERIC Negotiator Service API. The Service is running at
    [https://negotiator.bbmri-eric.eu](https://negotiator.bbmri-eric.eu)
paths:
  /status:
    get:
      tags:
        - v2
      summary: Get version and statistics of the called Negotiator instance.
      description: Listes depoyed version of the BBMRI-ERIC Negotiator service, basic statistic of the service.
      responses:
        '200':
          description: Successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Status'
        '400':
          description: Invalid status value
  /directory/create_query:
    post:
      tags:
        - v2
      summary: Creates a new query.
      description: Takes a JSON query object with information of the search criteria and results of the directory. Stores it temporary in the database and returns a redirect URL for the directory. With this URL the directory can redirect the user to the query edit page. I case of updating a existing query or extending an exiting request, a token is provided for identification.
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '201':
          description: successful created
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/QueryCreateResponse'
      deprecated: true
  /v2/list:
    get:
      tags:
        - list
      summary: List of Biobanks and Collections in all directories
      description: Returns a JSON array with a hierarchical structure of all directories integrated into the \Negotiator. For each directory all biobanks registered are listed with the identifying ID of the directory. In the biobank a list of all associated collections is listed.
      responses:
        '200':
          description: successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/List'
  /v2/io/export:
    get:
      tags:
        - request
      summary: Get request details by requestId
      description: Get detailed data for a request by requestId
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              type: object
              properties:
                requestId:
                  type: integer
                  format: int64
                  example: 131
      responses:
        '200':
          description: successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Request'
  /v2/io/import:
    post:
      tags:
        - request
      summary: Import a request to negotiator
      description: Import a request to negotiator
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          description: successful operation
          content:
            'application/json':
              schema:
                type: object
                properties:
                  requestId:
                    type: integer
                    format: int64
                    example: 131
                  requestURL:
                    type: string
  /perun/users:
    post:
      tags:
        - perun
      summary: Update AAI user information
      description: Update AAI user information from biobanks and collections
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AAIUser'
      responses:
        '200':
          description: successful operation
  /perun/networks/users:
    post:
      tags:
        - perun
      summary: Update AAI user information for network users
      description: Update AAI user information from networks
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AAIUserMapping'
      responses:
        '200':
          description: successful operation
  /perun/mapping:
    post:
      tags:
        - perun
      summary: Update AAI user collection mapping
      description: Update AAI user collections mapping
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AAIUser'
      responses:
        '200':
          description: successful operation
  /perun/networks/mapping:
    post:
      tags:
        - perun
      summary: Update AAI user network mapping
      description: Update AAI user network mapping
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AAIUser'
      responses:
        '200':
          description: successful operation
  /v3/data-sources:
    get:
      tags:
        - V3
        - Data Sources
      summary: Gets the list of data sources registered in this Negotiator
      responses:
        '200':
          description: Successful operation
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSource'
  /v3/data-sources/{dataSourceId}:
    get:
      tags:
        - V3
        - Data Sources
      summary: Retrieves data of a data source
      description: Retrieves data of the data source identified by data-source-id
      parameters:
        - name: dataSourceId
          in: path
          schema:
            type: string
          required: true
          description: the id of the data source to retrieve
      responses:
        '200':
          description: Successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DataSource'
        '404':
          description: Data source with the specified id not found in the Negotiator
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/queries:
    post:
      tags:
        - V3
        - Queries
      summary: Creates a query for a Data Source
      description: Create a query for the data source identified by {dataSourceId}
      parameters:
        - name: Prefer
          in: header
          schema:
            type: string
            enum:
              - return=representation
              - return=minimal
            default: return=minimal
          required: false
          description: specifies whether to return all data of the created query or just the id. By default it just the id is returned
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/QueryCreateV3'
      responses:
        '201':
          description: Query created correctly
          headers:
            Location:
              schema:
                type: string
              description:
                the location of the newly created query (e.g., /v3/data-sources/{dataSourceId}/queries/1)
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/QueryResponseV3'
        '400':
          description: There was an error in the request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data source with the specified id not found in the Negotiator
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/queries/{queryId}:
    get:
      tags:
        - V3
        - Queries
      summary: Retrieves data of a specific query
      parameters:
        - name: queryId
          in: path
          schema:
            type: string
          required: true
          description: the id of the query to retrieve
      responses:
        '200':
          description: Query created correctly
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/QueryResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data source or Query with the specified id not found in the Negotiator
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/projects:
    post:
      tags:
        - V3
        - Projects
      summary: Create a new project in the negotiator
      description: Create a new project in the negotiator
      parameters:
        - name: Prefer
          in: header
          schema:
            type: string
            enum:
              - return=representation
              - return=minimal
            default: return=minimal
          required: false
          description: specifies whether to return all data of the created project or just the id. By default just the id is returned
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ProjectCreateV3'
      responses:
        '201':
          description: successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProjectCreateResponseV3'
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - V3
        - Projects
      summary: Get the list of projects
      description: Get the list of projects. It is possible to filter by user id
      parameters:
        - name: user
          in: query
          schema:
            type: integer
            format: int64
          description: the id of the user used to filter the projects
      responses:
        '200':
          description: successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProjectCreateResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/projects/{projectId}:
    put:
      tags:
        - V3
        - Projects
      summary: Update the project identified by Id
      description: Update the project identified by Id
      parameters:
        - name: projectId
          in: path
          description: Id of project to return
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ProjectCreateV3'
      responses:
        '204':
          description: Project updated correctly
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - V3
        - Projects
      summary: Retrieve a project in the negotiator by Id
      description: Retrieve a project in the negotiator by Id
      parameters:
        - name: projectId
          in: path
          description: Id of project to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProjectCreateResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/requests:
    post:
      tags:
        - V3
        - Requests
      summary: Creates a new request with and the project it belongs to
      description: Endpoint to create a request and also its project.
        > To create a request for a previous project check `/v3/project/{projectId}/requests` endpoint
      parameters:
        - name: Prefer
          in: header
          schema:
            type: string
            enum:
              - return=representation
              - return=minimal
            default: return=minimal
          required: false
          description: specifies whether to return all data of the created request or just the id. By default it just the id is returned
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/RequestCreateV3WithProject'
      responses:
        '201':
          description: Request created successfully
          headers:
            Location:
              schema:
                type: string
              description:
                The location of the newly created request (e.g., /v3/requests/1)
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/RequestResponseV3'
    get:
      summary: Gets a list of Requests. They can be filtered by biobank or collection
      tags:
        - v3
        - Requests
      parameters:
        - name: bioankId
          in: query
          schema:
            type: string
          required: false
          description: specifies the data source id of a biobank the request is sent to
        - name: collectionId
          in: query
          schema:
            type: string
          required: false
          description: specifies the data source id of a collection the request is sent to
      responses:
        '200':
          description: The list of requests corresponding to filter createria (if any)
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/projects/{projectId}/requests:
    post:
      tags:
        - V3
        - Requests
      summary: Creates a new request for the project with id {projectId}
      description: Endpoint to create a request for a previously create project.
        > In this case the project data should not sent in the request
      parameters:
        - name: Prefer
          in: header
          schema:
            type: string
            enum:
              - return=representation
              - return=minimal
            default: return=minimal
          required: false
          description: specifies whether to return all data of the created request or just the id. By default it just the id is returned
        - name: projectId
          in: path
          description: Id of the project associated to the request
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/RequestCreateV3'
      responses:
        '201':
          description: Request created successfully
          headers:
            Location:
              schema:
                type: string
              description:
                The location of the newly created request (e.g., /v3/requests/1)
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/RequestResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/requests/{requestId}:
    parameters:
      - name: requestId
        in: path
        schema:
          type: integer
          format: int64
        required: true
        description: The id of the request to get/update
    put:
      tags:
        - V3
        - Requests
      summary: Updates the request with id {requestId}
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/RequestCreateV3'
      responses:
        '204':
          description: Request updated successfully
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - V3
        - Requests
      summary: Retrieves the request with id {requestId}
      responses:
        '200':
          description: Request updated successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/RequestResponseV3'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/users/:
    get:
      tags:
        - v3
      description: Endpoint used to search for users by some parameters ids
      parameters:
        - name: projectId
          in: query
          schema:
            type: integer
            format: int64
          required: false
          description: specifies the id of the project the users are involved in
        - name: requestId
          in: query
          schema:
            type: integer
            format: int64
          required: false
          description: specifies the id of the request the users are involved in
      responses:
        '200':
          description: Successful search
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserV3'
        '400':
          description: Bad request
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The user has no permission to perform this operation
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Status:
      type: object
      properties:
        biobanks:
          type: integer
          format: int64
          example: 1791
          description: number of registered biobanks in the Negotiator instance
        attachments:
          type: integer
          format: int64
          example: 111
          description: number of attachments uploaded into the system
        collections:
          type: integer
          format: int64
          example: 4515
          description: number of registered collections in the Negotiator instance
        queriesWithMatches:
          type: integer
          format: int64
          example: 271
          description: number of queries with at least one matching collection
        buildTime:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2020-09-10 11:25
          description: date/time when current Negotiator version was built
        used:
          type: integer
          format: int64
          example: 49476
          description: used diskspace on the system
        free:
          type: integer
          format: int64
          example: 49173
          description: free diskspace on the system
        queries:
          type: integer
          format: int64
          example: 285
          description: total number of queries registered in the Negotiator instance
        version:
          type: string
          example: 2.1.2-SNAPSHOT
          description: version of the Negotiator instance
        users:
          type: integer
          format: int64
          example: 364
          description: number of users registered  in the Negotiator instance
    Query:
      type: object
      properties:
        URL:
          type: string
        humanReadable:
          type: string
        collections:
          type: array
          items:
            type: object
            properties:
              biobankId:
                type: string
              collectionId:
                type: string
    QueryCreateResponse:
      type: object
      properties:
        redirect_uri:
          type: string
    List:
      type: array
      items:
        type: object
        properties:
          directory:
            type: object
            properties:
              name:
                type: string
              url:
                type: string
              description:
                type: string
              Biobanks:
                type: array
                items:
                  type: object
                  properties:
                    directory_id:
                      type: string
                    name:
                      type: string
                    collections:
                      type: array
                      items:
                        type: object
                        properties:
                          directory_id:
                            type: string
                          name:
                            type: string
    AAIUser:
      type: array
      items:
        type: object
        properties:
          organization:
            type: string
          id:
            type: integer
            format: int64
          displayName:
            type: string
          status:
            type: string
          mail:
            type: string
          identities:
            type: array
            items:
              type: string
    AAIUserMapping:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          directory:
            type: string
          id:
            type: string
          members:
            type: array
            items:
              type: object
              properties:
                userId:
                  type: string
    Request:
      type: object
      properties:
        requestId:
          type: integer
          format: int64
        title:
          type: string
        projectDescription:
          type: string
        requestDescription:
          type: string
        ethicsVote:
          type: string
        testRequest:
          type: boolean
        creationTime:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2020-09-10 11:25
          description: date/time when request was created
        collections:
          type: array
          description: array of collection involved in the request (optional)
          items:
            type: object
            properties:
              biobankId:
                type: string
              collectionId:
                type: string
        query:
          type: array
          items:
            type: object
            description: array of queries for the request (optional)
            properties:
              queryParameters:
                type: string
              humanReadable:
                type: string
                example: selected countries are AT
                description: human readable version of the query
              url:
                type: string
                description: redirect url to the directory
              numberOfCollections:
                type: integer
                format: int64
    DataSource:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of the data source in the negotiator
        name:
          type: string
          description: Name of the DataSource
        url:
          type: string
          description: URL of the DataSource
        description:
          type: string
          description: Description of the DataSource
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
    Resource:
      type: object
      properties:
        id:
          type: string
          description: Id of the resource in the datasource
        type:
          type: string
          description: The type of resource (biobank, collections, etc.)
        name:
          type: string
          description: Name of the resource in the data source
        children:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
    QueryCreateV3:
      type: object
      properties:
        url:
          type: string
        humanReadable:
          type: string
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
    QueryV3:
      allOf:
        - $ref: '#/components/schemas/QueryCreateV3'
        - type: object
          properties:
            id:
              type: integer
              format: int64
              description: Id of the query generated
    QueryResponseV3:
      allOf:
        - $ref: '#/components/schemas/QueryV3'
        - type: object
          properties:
            redirectUrl:
              type: string
    RequestCreateV3:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        isTest:
          type: boolean
        queries:
          type: array
          items:
            type: integer
            format: int64
            description: "List of IDs of queries related to the request"
    RequestCreateV3WithProject:
      allOf:
        - $ref: '#/components/schemas/RequestCreateV3'
        - type: object
          properties:
            project:
              $ref: '#/components/schemas/ProjectCreateV3'
    RequestResponseV3:
      type: object
      allOf:
        - $ref: '#/components/schemas/RequestCreateV3'
        - properties:
            id:
              type: integer
              format: int64
              description: Id of the generated request
    ProjectCreateV3:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        ethicsVote:
          type: string
        expectedDataGeneration:
          type: boolean
        expectedEndDate:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: "2020-09-10"
          description: date when project will probably end
    ProjectCreateResponseV3:
      allOf:
        - $ref: '#/components/schemas/ProjectCreateV3'
        - type: object
          properties:
            id:
              type: integer
              format: int64
            creationTime:
              type: string
              pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
              example: 2020-09-10 11:25
              description: date/time when project was created
    UserV3:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: the id of the user
        auth_subject:
          type: string
        auth_name:
          type: string
          description: user name
        auth_email:
          type: string
        organization:
          type: string
        is_admin:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: A code of the error
        message:
          type: string
          description: A short message describing the error