openapi: 3.0.3
info:
  title: Ensembl Resolver API
  description: Resolver API resolves external urls to Ensembl
  contact:
    email: ensembl-webteam@ebi.ac.uk
  version: 0.8.0
servers:
  # Keep these server URLs explicit for now because the resolver is mounted at
  # different base paths in different environments. In particular, dev uses the
  # /api/resolver prefix, while review/local do not.
  #
  # Swagger UI will use one of these configured servers when making requests from
  # the docs page. If an environment is not listed here, or if its base path
  # changes, the docs may send requests to the wrong resolver endpoint.
  #
  # Longer term, life would be simpler if we moved away from the dev
  # /api/resolver prefix and used review environments only, so each deployment
  # could point Swagger UI at itself without special-case server URLs.
  - url: https://resolver.ensembl.org
    description: Production
  - url: https://dev-2020.ensembl.org/api/resolver
    description: Development
  - url: https://test-resolver.review.ensembl.org
    description: Review
  - url: http://localhost:8001
    description: Local
tags:
  - name: Resolver
    description: Resolver API resolves external urls to Ensembl
  - name: Rapid Resolver
    description: Resolver API to resolve rapid site urls to Ensembl
  - name: URL Resolver
    description: Resolver API to resolve legacy Ensembl URLs to new Ensembl URLs
paths:
  /id/{stable_id}:
    get:
      tags:
        - Resolver
      summary: Resolve stable ID with optional query params
      description: Resolves to a new Ensembl URL when a stable id wih optional query params provided
      parameters:
        - name: stable_id
          in: path
          description: Gene, transcript, or protein stable ID.
          required: true
          explode: true
          schema:
            type: string
            example: ENSG00000221914.11
        - name: type
          in: query
          description: Optional stable-ID type filter. If omitted, all supported types are searched.
          required: false
          schema:
            type: string
            enum: [ gene, transcript, protein ]
        - name: app
          in: query
          description: Choose between apps - Genome Browser/ Feature Explorer
          required: false
          schema:
            type: string
            enum: [ genome-browser, feature-explorer ]
        - name: gca
          in: query
          description: GCA assembly accession id of the genome
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    assembly:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Assembly name
                        accession_id:
                          type: string
                          description: Assembly accession id
                    scientific_name:
                      type: string
                      description: Species scientific name
                    common_name:
                      type: string
                      description: Species common name
                    type:
                      type: string
                      description: Genome type
                    resolved_url:
                      type: string
                      description: Resolved url to Ensembl site
                    is_reference:
                      type: boolean
                      description: Whether a genome is reference or not
        '302':
          description: Redirect to resolved URL
          headers:
            Location:
              schema:
                type: string
          content: {}
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid:
    get:
      summary: Resolve rapid site url
      description: Resolves to Ensembl site url (home page).
      tags:
        - Rapid Resolver
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/id/{stable_id}:
    get:
      tags:
        - Rapid Resolver
      summary: Resolve Rapid stable ID
      description: Resolves to a new Ensembl URL when a stable id
      parameters:
        - name: stable_id
          in: path
          description: Gene stable id used to represent a gene in a genome.
          required: true
          schema:
            type: string
            example: ENSG00000221914.11
      responses:
        '200':
          description: OK
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    assembly:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Assembly name
                        accession_id:
                          type: string
                          description: Assembly accession id
                    scientific_name:
                      type: string
                      description: Species scientific name
                    common_name:
                      type: string
                      description: Species common name
                    type:
                      type: string
                      description: Genome type
                    feature_explorer_url:
                      type: string
                      description: Resolved Ensembl Feature Explorer url
                    genome_browser_url:
                      type: string
                      description: Resolved Ensembl genome browser url
                    is_reference:
                      type: boolean
                      description: Whether a genome is reference or not
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/Multi/Tools/Blast:
    get:
      summary: Resolve rapid site blast url
      description: Resolves to Ensembl site blast url.
      tags:
        - Rapid Resolver
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/{species_url_name}:
    get:
      summary: Resolve rapid site url with species url name (with assembly accession)
      description: Resolves to Ensembl site url with the species url name provided.
      tags:
        - Rapid Resolver
      parameters:
        - name: species_url_name
          in: path
          description: Species name with assembly accession
          required: true
          schema:
            type: string
            example: Camarhynchus_parvulus_GCA_902806625.1
      responses:
        '200':
          $ref: '#/components/responses/200'
        '422':
          $ref: '#/components/responses/422'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/{species_url_name}/{subpath}:
    get:
      summary: Resolve rapid site url with species url name and subpath
      description: Resolves to Ensembl site url with the species url name and subpath provided.
      tags:
        - Rapid Resolver
      parameters:
        - name: species_url_name
          in: path
          description: Species name with assembly accession
          required: true
          schema:
            type: string
            example: Camarhynchus_parvulus_GCA_902806625.1
        - name: subpath
          in: path
          description: Additional path under species_url_name
          required: true
          schema:
            type: string
            example: Location/View
        - name: r
          in: query
          required: false
          description: Region string
          schema:
            type: string
            example: 2:361680-384534
      responses:
        '200':
          $ref: '#/components/responses/200'
        '422':
          $ref: '#/components/responses/422'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/{species_url_name}/Tools/Blast:
    get:
      summary: Resolve rapid site blast url
      description: Resolve rapid site blast url
      tags:
        - Rapid Resolver
      parameters:
        - name: species_url_name
          in: path
          description: Species name with assembly accession
          required: true
          schema:
            type: string
            example: Camarhynchus_parvulus_GCA_902806625.1
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /rapid/info/{subpath}:
    get:
      summary: Resolve rapid site help and docs url
      description: Resolves to Ensembl site help page url.
      tags:
        - Rapid Resolver
      parameters:
        - name: subpath
          in: path
          required: true
          schema:
            type: string
            example: index.html
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /legacy:
    get:
      summary: Resolve legacy Ensembl URL
      description: Resolves a supported legacy Ensembl URL to its new Ensembl equivalent, or redirects browser requests for unresolved URLs to the matching configured archive host.
      tags:
        - URL Resolver
      parameters:
        - name: url
          in: query
          description: Full legacy Ensembl URL or path to resolve.
          required: true
          schema:
            type: string
            example: https://www.ensembl.org/Homo_sapiens/Gene/Summary?g=ENSG00000012048
      responses:
        '200':
          $ref: '#/components/responses/200'
        '308':
          description: Redirect to resolved new Ensembl URL
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content: {}
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  headers:
    Location:
      description: Ensembl URL
      schema:
        type: string
  responses:
    200:
      description: OK
      headers:
        Location:
          $ref: '#/components/headers/Location'
      content:
        application/json:
          schema:
            type: object
            properties:
              resolved_url:
                type: string
                description: Resolved URL to the Ensembl site
    400:
      description: Bad Request. Missing stable id in the url
      content:
        text/plain:
          schema:
            type: string
            example: "Bad request"
        application/json:
          schema:
            example: '{"status_code": 400, "details": "Bad request"}'
    404:
      description: Requested url not found
      content:
        text/plain:
          schema:
            type: string
            example: "Not found"
        application/json:
          schema:
            example: '{"status_code": 404, "details": "Not found"}'
    422:
      description: Unprocessable Content
      content:
        application/json:
          schema:
            example: '{"status_code": 422, "detail": "Unable to process input accession ID"}'
    500:
      description: Internal server error
      content:
        text/plain:
          schema:
            type: string
            example:
              Internal server error
        application/json:
          schema:
            example: '{"status_code": 500, "details": "Internal server error"}'