swagger: "2.0"
info:
  version: "0.0.1"
  title: OpenTrials API
basePath: /v1
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /swagger.yaml:
    x-swagger-pipe: swagger_raw

  /search:
    x-swagger-router-controller: search
    get:
      tags:
        - trials
      description: Search trials
      operationId: search
      parameters:
        - name: q
          in: query
          description: The search query
          type: string
        - name: page
          in: query
          description: The page number
          type: integer
          minimum: 1
          maximum: 100
          default: 1
        - name: per_page
          in: query
          description: Number of items per page
          type: integer
          minimum: 10
          maximum: 100
          default: 20
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/TrialSearchResults"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /search/autocomplete/{in}:
    x-swagger-router-controller: search
    get:
      tags:
        - search
      description: Search locations
      operationId: autocomplete
      parameters:
        - name: q
          in: query
          description: The search query
          type: string
        - name: page
          in: query
          description: The page number
          type: integer
          minimum: 1
          maximum: 100
          default: 1
        - name: per_page
          in: query
          description: Number of items per page
          type: integer
          minimum: 10
          maximum: 100
          default: 20
        - name: in
          in: path
          required: true
          description: The entity to search for
          type: string
          enum:
            - condition
            - intervention
            - location
            - person
            - organisation
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/AutocompleteResults"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /trials/{id}:
    x-swagger-router-controller: trials
    get:
      tags:
        - trials
      description: Returns trial details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the trial
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Trial"
        "404":
          description: Trial not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /publications/{id}:
    x-swagger-router-controller: publications
    get:
      tags:
        - publications
      description: Returns publication details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the publictaion
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Publication"
        "404":
          description: Publictaion not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /conditions/{id}:
    x-swagger-router-controller: conditions
    get:
      tags:
        - conditions
      description: Returns condition details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the condition
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Condition"
        "404":
          description: Condition not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /organisations/{id}:
    x-swagger-router-controller: organisations
    get:
      tags:
        - organisations
      description: Returns organisation details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the organisation
          required: true
          type: string
      responses:
        "200":
           description: Success
           schema:
            $ref: "#/definitions/Organisation"
        "404":
          description: Organisation not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /trials/{id}/records:
    x-swagger-router-controller: trials
    get:
      tags:
        - trials
      description: Returns all trial's raw records from its sources
      operationId: getRecords
      parameters:
        - name: id
          in: path
          description: ID of the trial
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/RecordList"
        "404":
          description: Trial not found

  /trials/{trialId}/records/{id}:
    x-swagger-router-controller: trials
    get:
      tags:
        - trials
      description: Returns a trial's raw record from its sources
      operationId: getRecord
      parameters:
        - name: trialId
          in: path
          description: ID of the trial
          required: true
          type: string
        - name: id
          in: path
          description: ID of the trial's record
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Record"
        "404":
          description: Trial not found

  /persons/{id}:
    x-swagger-router-controller: persons
    get:
      tags:
        - persons
      description: Returns person details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the person
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Person"
        "404":
          description: Person not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /interventions/{id}:
    x-swagger-router-controller: interventions
    get:
      tags:
        - interventions
      description: Returns intervention details
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the intervention
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Intervention"
        "404":
          description: Intervention not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /stats:
    x-swagger-router-controller: stats
    get:
      tags:
        - statistics
      description: Returns statistics
      operationId: get
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/Stats"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

definitions:
  Stats:
    type: object
    properties:
      trialsCount:
        type: integer
        description: Trials count
      trialsPerSource:
        type: array
        items:
          $ref: '#/definitions/TrialsPerSource'
      trialsPerYear:
        type: array
        items:
          $ref: '#/definitions/TrialsPerYear'
      topLocations:
        type: array
        items:
          $ref: '#/definitions/TopLocations'
      sourcesLatestUpdatedDate:
        type: array
        items:
          $ref: '#/definitions/SourcesLatestUpdatedDate'

  TrialsPerSource:
    type: object
    properties:
      id:
        type: string
        description: Source's ID
      name:
        type: string
        description: Source's name
      count:
        type: integer
        description: Number of trials in this source

  TrialsPerYear:
    type: object
    properties:
      year:
        type: integer
      count:
        type: integer
        description: Number of trials in this year

  TopLocations:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      count:
        type: integer
        description: Number of trials in this location

  SourcesLatestUpdatedDate:
    type: object
    description: Source with information on when it was last updated
    properties:
      id:
        type: string
      name:
        type: string
      latest_updated_date:
        type: string
        description: Date this source was last updated

  Trial:
    required:
      - id
      - url
      - public_title
      - locations
      - interventions
      - persons
      - organisations
      - records
      - publications
    properties:
      id:
        type: string
      source_id:
        type: string
      identifiers:
        type: object
        description: Object that maps the Trial's sources ids with its identifiers.
      url:
        type: string
      public_title:
        type: string
      brief_summary:
        type: string
      target_sample_size:
        type: integer
        minimum: 0
      gender:
        type: string
        enum:
          - both
          - male
          - female
      has_published_results:
        type: boolean
      registration_date:
        type: string
        format: date-time
      status:
        type: string
        enum:
          - ongoing
          - withdrawn
          - suspended
          - terminated
          - complete
          - other
      recruitment_status:
        type: string
        enum:
          - recruiting
          - not_recruiting
          - unknown
          - other
      locations:
        type: array
        items:
          $ref: '#/definitions/TrialLocation'
      interventions:
        type: array
        items:
          $ref: '#/definitions/Intervention'
      conditions:
        type: array
        items:
          $ref: '#/definitions/Condition'
      persons:
        type: array
        items:
          $ref: '#/definitions/TrialPerson'
      organisations:
        type: array
        items:
          $ref: '#/definitions/TrialOrganisation'
      records:
        type: array
        items:
          $ref: '#/definitions/RecordSummary'
      publications:
        type: array
        items:
          $ref: '#/definitions/PublicationSummary'
      discrepancies:
        type: object
        items:
          $ref: '#/definitions/Discrepancies'
      documents:
        type: array
        items:
          $ref: '#/definitions/Document'

  TrialLocation:
    allOf:
      - $ref: '#/definitions/Location'
      - type: object
        properties:
          role:
            type: string
            enum:
              - recruitment_countries
              - other

  Location:
    required:
      - id
      - name
      - url
    properties:
      id:
        type: string
      name:
        type: string
      url:
        type: string
      type:
        type: string
        enum:
          - country
          - city
          - other

  Intervention:
    required:
      - id
      - name
      - url
    properties:
      id:
        type: string
      name:
        type: string
      url:
        type: string
      type:
        type: string
        enum:
          - drug
          - other

  Condition:
    required:
      - id
      - name
      - url
    properties:
      id:
        type: string
      name:
        type: string
      url:
        type: string

  TrialPerson:
    allOf:
      - $ref: '#/definitions/Person'
      - type: object
        properties:
          role:
            type: string
            enum:
              - principal_investigator
              - public_queries
              - scientific_queries
              - other
  Person:
    required:
      - id
      - name
      - url
    properties:
      id:
        type: string
      name:
        type: string
      url:
        type: string
      type:
        type: string
        enum:
          - other

  TrialOrganisation:
    allOf:
      - $ref: '#/definitions/Organisation'
      - type: object
        properties:
          role:
            type: string
            enum:
              - primary_sponsor
              - sponsor
              - funder
              - other
  Organisation:
    required:
      - id
      - name
      - url
    properties:
      id:
        type: string
      name:
        type: string
      url:
        type: string

  RecordList:
    type: array
    items:
      $ref: '#/definitions/Record'

  Record:
    required:
      - id
      - url
      - trial_id
      - trial_url
      - source
      - source_url
      - source_data
      - public_title
      - created_at
      - updated_at
    properties:
      id:
        type: string
      identifiers:
        type: object
        description: Object that maps the Trial's sources ids with its identifiers.
      source_id:
        type: string
      url:
        type: string
      trial_id:
        type: string
      trial_url:
        type: string
      source:
        $ref: '#/definitions/Source'
      source_url:
        type: string
      source_data:
        type: object
      public_title:
        type: string
      status:
        type: string
        enum:
          - ongoing
          - withdrawn
          - suspended
          - terminated
          - complete
          - other
      recruitment_status:
        type: string
        enum:
          - recruiting
          - not_recruiting
          - unknown
          - other
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time

  Publication:
    required:
      - id
      - url
      - source
      - source_url
      - title
      - abstract
    properties:
      id:
        type: string
      url:
        type: string
      source:
        $ref: '#/definitions/Source'
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
      source_url:
        type: string
      title:
        type: string
      abstract:
        type: string
      authors:
        type: array
        items:
          type: string
      journal:
        type: string
      date:
        type: string
        format: date-time
      slug:
        type: string

  RecordSummary:
    required:
      - id
      - url
      - source
    properties:
      id:
        type: string
      url:
        type: string
      source:
        $ref: '#/definitions/Source'

  PublicationSummary:
    required:
      - id
      - url
      - title
      - source
    properties:
      id:
        type: string
      url:
        type: string
      title:
        type: string
      source:
        $ref: '#/definitions/Source'

  Discrepancies:
    description: Object listing the Trial's discrepant fields
    properties:
      gender:
        type: array
        items:
          $ref: '#/definitions/DiscrepantFieldString'
      target_sample_size:
        type: array
        items:
          $ref: '#/definitions/DiscrepantFieldInteger'
      status:
        type: array
        items:
          $ref: '#/definitions/DiscrepantFieldString'
      recruitment_status:
        type: array
        items:
          $ref: '#/definitions/DiscrepantFieldString'
      has_published_results:
        type: array
        items:
          $ref: '#/definitions/DiscrepantFieldBoolean'

  DiscrepantFieldString:
    allOf:
      - $ref: '#/definitions/DiscrepancyFieldBase'
      - type: object
        properties:
          value:
            type: string

  DiscrepantFieldInteger:
    allOf:
      - $ref: '#/definitions/DiscrepancyFieldBase'
      - type: object
        properties:
          value:
            type: integer

  DiscrepantFieldBoolean:
    allOf:
      - $ref: '#/definitions/DiscrepancyFieldBase'
      - type: object
        properties:
          value:
            type: boolean

  DiscrepancyFieldBase:
    required:
      - record_id
      - source_name
    properties:
      record_id:
        type: string
      source_name:
        type: string

  Document:
    required:
      - name
      - type
      - url
    properties:
      name:
        type: string
      type:
        type: string
        enum:
          - csr
          - csr_synopsis
          - epar_segment
          - blank_consent_form
          - patient_information_sheet
          - blank_case_report_form
          - results
          - other
      url:
        type: string
      documentcloud_id:
        type: string
      text:
        type: string

  Source:
    required:
      - id
      - name
    properties:
      id:
        type: string
      name:
        type: string
      type:
        type: string
        enum:
          - register
          - other

  TrialSearchResults:
    required:
      - total_count
      - items
    properties:
      total_count:
        type: integer
      items:
        type: array
        items:
          $ref: '#/definitions/Trial'

  AutocompleteResults:
    required:
      - total_count
      - items
    properties:
      total_count:
        type: integer
      items:
        type: array
        items:
          $ref: '#/definitions/AutocompleteResult'

  AutocompleteResult:
    required:
      - id
      - name
    properties:
      id:
        type: string
      name:
        type: string

  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string