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:
            - problem
            - 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
      # used as the method name of the controller
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the trial
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/Trial"
        # responses may fall through to errors
        "404":
          description: Trial not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /problems/{id}:
    x-swagger-router-controller: problems
    get:
      tags:
        - problems
      description: Returns problem details
      # used as the method name of the controller
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the problem
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/Problem"
        # responses may fall through to errors
        "404":
          description: Problem not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

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

  /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
      # used as the method name of the controller
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the person
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/Person"
        # responses may fall through to errors
        "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
      # used as the method name of the controller
      operationId: get
      parameters:
        - name: id
          in: path
          description: ID of the intervention
          required: true
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/Intervention"
        # responses may fall through to errors
        "404":
          description: Intervention not found
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"


  /locations:
    x-swagger-router-controller: locations
    get:
      tags:
        - locations
      description: Returns list of locations
      operationId: list
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/LocationList"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

# complex objects have schema definitions
definitions:
  Trial:
    required:
      - id
      - url
      - public_title
      - brief_summary
      - registration_date
      - locations
      - interventions
      - persons
      - organisations
      - records
    properties:
      id:
        type: string
      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
      locations:
        type: array
        items:
          $ref: '#/definitions/TrialLocation'
      interventions:
        type: array
        items:
          $ref: '#/definitions/TrialIntervention'
      problems:
        type: array
        items:
          $ref: '#/definitions/TrialProblem'
      persons:
        type: array
        items:
          $ref: '#/definitions/TrialPerson'
      organisations:
        type: array
        items:
          $ref: '#/definitions/TrialOrganisation'
      records:
        type: array
        items:
          $ref: '#/definitions/RecordSummary'

  TrialLocation:
    required:
      - attributes
    properties:
      role:
        type: string
        enum:
          - recruitment_countries
          - other
      attributes:
        $ref: '#/definitions/Location'
  Location:
    required:
      - id
      - name
    properties:
      id:
        type: string
      name:
        type: string
      type:
        type: string
        enum:
          - country
          - city
          - other

  TrialIntervention:
    required:
      - attributes
    properties:
      role:
        type: string
        enum:
          - other
      attributes:
        $ref: '#/definitions/Intervention'
  Intervention:
    required:
      - id
      - name
    properties:
      id:
        type: string
      name:
        type: string
      type:
        type: string
        enum:
          - drug
          - other

  TrialProblem:
    required:
      - attributes
    properties:
      role:
        type: string
        enum:
          - other
      attributes:
        $ref: '#/definitions/Problem'
  Problem:
    required:
      - id
      - name
    properties:
      id:
        type: string
      name:
        type: string
      type:
        type: string
        enum:
          - condition
          - other

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

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

  Record:
    required:
      - id
      - url
      - trial_id
      - trial_url
      - source
      - source_url
      - source_data
      - public_title
      - created_at
      - updated_at
    properties:
      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
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time

  RecordSummary:
    required:
      - id
      - url
      - source
    properties:
      id:
        type: string
      url:
        type: string
      source:
        $ref: '#/definitions/Source'
  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

  LocationList:
    type: array
    items:
      $ref: '#/definitions/Location'

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