openapi: 3.1.0

info:
  title: mentaxonomy API
  version: 1.0.0
  description: |
    mentaxonomy provides a unified API for resolving taxonomic names
    using external taxonomy providers.

    Taxonomic status fields:

    - status: normalized status of the requested taxon.
    - provider_status: original status reported by the provider.
    - accepted_status: normalized status of the accepted taxon.
servers:
  - url: /
    description: Current server

paths:

  /v1/taxon:

    get:

      summary: Resolve a taxon

      description: >
        Returns a normalized taxonomic record for the requested provider
        and taxon identifier.

      parameters:

        - name: provider
          in: query
          required: true
          description: Taxonomic provider.
          schema:
            type: string
            enum:
              - lpsn
              - mycobank
          example: lpsn

        - name: id
          in: query
          required: true
          description: Provider taxon identifier.
          schema:
            type: integer
            minimum: 1
          example: 772469

      responses:

        '200':
          description: Successful response

          content:

            application/json:

              schema:
                $ref: '#/components/schemas/Taxon'

              examples:

                synonym:

                  summary: Synonym

                  value:

                    provider: lpsn
                    taxon_id: 772469
                    rank: species
                    name: Abiotrophia elegans
                    authority: Roggenkamp et al. 1999
                    status: synonym

                    accepted_taxon_id: 771183
                    accepted_name: Granulicatella elegans
                    accepted_authority: "(Roggenkamp et al. 1999) Collins and Lawson 2000"
                    accepted_status: correct name

                    source_url: https://lpsn.dsmz.de/species/abiotrophia-elegans
                    accepted_source_url: https://lpsn.dsmz.de/species/granulicatella-elegans

        '400':

          description: Invalid request

          content:

            application/json:

              schema:
                $ref: '#/components/schemas/Error'

        '501':

          description: Provider unavailable

          content:

            application/json:

              schema:
                $ref: '#/components/schemas/Error'

        '500':

          description: Internal server error

          content:

            application/json:

              schema:
                $ref: '#/components/schemas/Error'


components:

  schemas:

    Taxon:

      type: object

      properties:

        provider:
          type: string

        taxon_id:
          type: integer

        rank:
          type:
            - string
            - "null"

        name:
          type:
            - string
            - "null"

        authority:
          type:
            - string
            - "null"

        status:
          type:
            - string
            - "null"

        accepted_taxon_id:
          type:
            - integer
            - "null"

        accepted_name:
          type:
            - string
            - "null"

        accepted_authority:
          type:
            - string
            - "null"

        accepted_status:
          type:
            - string
            - "null"

        source_url:
          type:
            - string
            - "null"
          format: uri

        accepted_source_url:
          type:
            - string
            - "null"
          format: uri

    Error:

      type: object

      properties:

        error:
          type: string