openapi: 3.0.1
info:
  title: Pathway Analysis Service database species API
  description: Provides an API for pathway over-representation and expression analysis as well as species comparison tool.
  termsOfService: /license
  contact:
    name: Reactome
    url: https://reactome.org
    email: help@reactome.org
  license:
    name: Creative Commons Attribution 3.0 Unsupported License
    url: https://creativecommons.org/licenses/by/3.0/legalcode
  version: '2.0'
servers:
- url: /AnalysisService
tags:
- name: species
  description: Species comparison
paths:
  /species/homoSapiens/{species}:
    get:
      tags:
      - species
      summary: Compares Homo sapiens to the specified species
      description: Use page and pageSize to reduce the amount of data retrieved. Use sortBy and order to sort the result by your preferred option. The resource field will filter the results to show only those corresponding to the preferred molecule type (TOTAL includes all the different molecules type)
      operationId: compareHomoSapiensTo
      parameters:
      - name: species
        in: path
        description: The dbId of the species to compare to
        required: true
        schema:
          type: integer
          format: int64
      - name: pageSize
        in: query
        description: pathways per page
        required: false
        schema:
          type: integer
          format: int32
        example: 20
      - name: page
        in: query
        description: page number
        required: false
        schema:
          type: integer
          format: int32
        example: 1
      - name: sortBy
        in: query
        required: false
        schema:
          type: string
          description: how to sort the result
          example: ENTITIES_PVALUE
          enum:
          - NAME
          - TOTAL_ENTITIES
          - TOTAL_INTERACTORS
          - TOTAL_REACTIONS
          - FOUND_ENTITIES
          - FOUND_INTERACTORS
          - FOUND_REACTIONS
          - ENTITIES_RATIO
          - ENTITIES_PVALUE
          - ENTITIES_FDR
          - REACTIONS_RATIO
      - name: order
        in: query
        required: false
        schema:
          type: string
          description: specifies the order
          example: ASC
          enum:
          - ASC
          - DESC
      - name: resource
        in: query
        required: false
        schema:
          type: string
          description: the resource to sort
          example: TOTAL
          enum:
          - TOTAL
          - UNIPROT
          - ENSEMBL
          - CHEBI
          - IUPHAR
          - MIRBASE
          - NCBI_PROTEIN
          - EMBL
          - COMPOUND
          - PUBCHEM_COMPOUND
      - name: pValue
        in: query
        description: defines the pValue threshold. Only hit pathway with pValue equals or below the threshold will be returned
        required: false
        schema:
          type: number
          format: double
          default: 1.0
        example: 1
      - name: min
        in: query
        description: minimum number of contained entities per pathway (takes into account the resource)
        required: false
        schema:
          type: integer
          format: int32
      - name: max
        in: query
        description: maximum number of contained entities per pathway (takes into account the resource)
        required: false
        schema:
          type: integer
          format: int32
      - name: importableOnly
        in: query
        description: Filters resources to only includes importable ones
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '404':
          description: Species identifier does not match with any of the species in the current data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResult'
  /data/species/all:
    get:
      tags:
      - species
      summary: The list of all species in Reactome
      description: This method retrieves the list of all species in Reactome knowledgebase, sorted by name.
      operationId: getAllSpecies
      parameters:
      - name: view
        in: query
        description: Global parameter - Customise the view to be more concise and/or aggregate relationships
        required: false
        schema:
          type: string
          default: flatten
          enum:
          - flatten
          - nested
          - nested-aggregated
          example: null
      - name: includeRef
        in: query
        description: Global parameter - If true, replace element ref to dbId by standard JSOG object {@ref}
        required: false
        schema:
          type: boolean
          default: false
          example: null
      responses:
        '406':
          description: Not acceptable according to the accept headers sent in the request
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /data/species/main:
    get:
      tags:
      - species
      summary: The list of main species in Reactome
      description: This method retrieves the list of main species in Reactome knowledgebase, sorted by name, but having 'Homo sapiens' as the first one. It should be mentioned that for Reactome, main species are considered those have either manually curated or computationally inferred pathways.
      operationId: getSpecies
      parameters:
      - name: view
        in: query
        description: Global parameter - Customise the view to be more concise and/or aggregate relationships
        required: false
        schema:
          type: string
          default: flatten
          enum:
          - flatten
          - nested
          - nested-aggregated
          example: null
      - name: includeRef
        in: query
        description: Global parameter - If true, replace element ref to dbId by standard JSOG object {@ref}
        required: false
        schema:
          type: boolean
          default: false
          example: null
      responses:
        '406':
          description: Not acceptable according to the accept headers sent in the request
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
components:
  schemas:
    AnalysisResult:
      type: object
      properties:
        expression:
          $ref: '#/components/schemas/ExpressionSummary'
        identifiersNotFound:
          type: integer
          format: int32
        pathways:
          type: array
          items:
            $ref: '#/components/schemas/PathwaySummary'
        pathwaysFound:
          type: integer
          format: int32
        resourceSummary:
          type: array
          items:
            $ref: '#/components/schemas/ResourceSummary'
        speciesSummary:
          type: array
          items:
            $ref: '#/components/schemas/SpeciesSummary'
        summary:
          $ref: '#/components/schemas/AnalysisSummary'
        warnings:
          type: array
          items:
            type: string
    PathwaySummary:
      type: object
      properties:
        dbId:
          type: integer
          format: int64
        entities:
          $ref: '#/components/schemas/EntityStatistics'
        inDisease:
          type: boolean
        llp:
          type: boolean
        name:
          type: string
        reactions:
          $ref: '#/components/schemas/ReactionStatistics'
        species:
          $ref: '#/components/schemas/SpeciesSummary'
        stId:
          type: string
    AnalysisSummary:
      type: object
      properties:
        fileName:
          type: string
        gsaMethod:
          type: string
        gsaToken:
          type: string
        includeDisease:
          type: boolean
        interactors:
          type: boolean
        projection:
          type: boolean
        sampleName:
          type: string
        species:
          type: integer
          format: int64
        text:
          type: boolean
        token:
          type: string
        type:
          type: string
    ResourceSummary:
      type: object
      properties:
        filtered:
          type: integer
          format: int32
        pathways:
          type: integer
          format: int32
        resource:
          type: string
    SpeciesSummary:
      type: object
      properties:
        dbId:
          type: integer
          format: int64
        filtered:
          type: integer
          format: int32
        name:
          type: string
        pathways:
          type: integer
          format: int32
        taxId:
          type: string
    EntityStatistics:
      type: object
      properties:
        curatedFound:
          type: integer
          format: int32
        curatedTotal:
          type: integer
          format: int32
        exp:
          type: array
          items:
            type: number
            format: double
        fdr:
          type: number
          format: double
        found:
          type: integer
          format: int32
        getpValue:
          type: number
          format: double
        interactorsFound:
          type: integer
          format: int32
        interactorsTotal:
          type: integer
          format: int32
        ratio:
          type: number
          format: double
        resource:
          type: string
        total:
          type: integer
          format: int32
    ReactionStatistics:
      type: object
      properties:
        found:
          type: integer
          format: int32
        ratio:
          type: number
          format: double
        resource:
          type: string
        total:
          type: integer
          format: int32
    ExpressionSummary:
      type: object
      properties:
        columnNames:
          type: array
          items:
            type: string
        max:
          type: number
          format: double
        min:
          type: number
          format: double