annif.yaml

openapi: 3.0.1
info:
  title: Annif REST API
  version: v1
servers:
- url: /v1
paths:
  /:
    get:
      tags:
      - API information
      summary: get basic information about the API service
      operationId: annif.rest.show_info
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInfo'
  /projects:
    get:
      tags:
      - Project administration
      summary: get a list of projects
      operationId: annif.rest.list_projects
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
  /projects/{project_id}:
    get:
      tags:
      - Project administration
      summary: show project information
      operationId: annif.rest.show_project
      parameters:
      - $ref: '#/components/parameters/project_id'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        "404":
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/suggest:
    post:
      tags:
      - Automatic subject indexing
      summary: suggest subjects for a given text
      operationId: annif.rest.suggest
      parameters:
      - $ref: '#/components/parameters/project_id'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: input text
                limit:
                  type: integer
                  description: maximum number of results to return
                  format: int32
                  default: 10
                  minimum: 0
                threshold:
                  type: number
                  description: minimum score threshold, below which results will not
                    be returned
                  default: 0.0
                  minimum: 0.0
                  maximum: 1.0
                language:
                  type: string
                  description: language of subject labels
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionResultList'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
  /projects/{project_id}/suggest-batch:
    post:
      tags:
      - Automatic subject indexing
      summary: suggest subjects for the given batch of up to 32 documents
      operationId: annif.rest.suggest_batch
      parameters:
      - $ref: '#/components/parameters/project_id'
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
          default: 10
          minimum: 0
        description: maximum number of results to return
      - in: query
        name: threshold
        schema:
          type: number
          default: 0.0
          minimum: 0.0
          maximum: 1.0
        description: minimum score threshold, below which results will not be returned
      - in: query
        name: language
        schema:
          type: string
        description: language of subject labels
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - documents
              properties:
                documents:
                  type: array
                  maxItems: 32
                  items:
                    $ref: '#/components/schemas/Document'
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSuggestionResultList'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
      x-codegen-request-body-name: documents
  /projects/{project_id}/learn:
    post:
      tags:
      - Learning from feedback
      summary: learn from manually indexed documents
      operationId: annif.rest.learn
      parameters:
      - $ref: '#/components/parameters/project_id'
      requestBody:
        description: documents to learn from
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/IndexedDocument'
        required: true
      responses:
        "204":
          description: successful operation
          content:
            application/json:
              {}
        "404":
          $ref: '#/components/responses/NotFound'
        "503":
          $ref: '#/components/responses/ServiceUnavailable'
      x-codegen-request-body-name: documents
  /detect-language:
    post:
      tags:
      - Language detection
      summary: detect the language of a text given a list of candidate languages
      operationId: annif.rest.detect_language
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              - languages
              properties:
                text:
                  type: string
                  description: input text
                  example: A quick brown fox jumped over the lazy dog.
                languages:
                  type: array
                  description: candidate languages as IETF BCP 47 codes
                  items:
                    type: string
                    maxLength: 3
                    minLength: 2
                    example: en
                  minItems: 1
                  maxItems: 5
        required: true
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectedLanguages'
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    ApiInfo:
      required:
      - title
      - version
      type: object
      properties:
        title:
          type: string
          example: Annif REST API
        version:
          type: string
          example: 0.60.0
      description: REST API information
    ProjectBackend:
      required:
      - backend_id
      type: object
      properties:
        backend_id:
          type: string
          example: my-backend
      description: A backend of a project
    Project:
      required:
      - backend
      - language
      - name
      - project_id
      type: object
      properties:
        project_id:
          type: string
          example: my-project
        name:
          type: string
          example: My Project
        language:
          type: string
          example: en
        backend:
          $ref: '#/components/schemas/ProjectBackend'
        is_trained:
          type: boolean
          example: true
          nullable: true
        modification_time:
          type: string
          format: date-time
          example: 2020-05-19T16:42:42Z
          nullable: true
      description: A project definition
    ProjectList:
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
      description: A list of projects
    SuggestionResult:
      required:
      - label
      - score
      - uri
      type: object
      properties:
        uri:
          type: string
          example: http://example.org/subject1
        label:
          type: string
          example: Archaeology
        notation:
          type: string
          example: "42.42"
          nullable: true
        score:
          type: number
          example: 0.85
      description: A single candidate subject for a document
    SuggestionResultList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SuggestionResult'
      description: A list of analysis results
    BatchSuggestionResultList:
      type: array
      items:
        allOf:
        - $ref: '#/components/schemas/SuggestionResultList'
        - type: object
          properties:
            document_id:
              type: string
              example: doc-1234
              nullable: true
      description: A list of batch analysis results
    Document:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          example: A quick brown fox jumped over the lazy dog.
        document_id:
          type: string
          example: doc-1234
      description: A document with an optional identifier
    IndexedDocument:
      type: object
      properties:
        text:
          type: string
          example: A quick brown fox jumped over the lazy dog.
        subjects:
          type: array
          items:
            type: object
            required:
              - uri
            properties:
              uri:
                type: string
                example: http://example.org/subject1
              label:
                type: string
                example: Vulpes vulpes
      description: A document with attached, known good subjects
    DetectedLanguages:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              language:
                type: string
                example: en
                nullable: true
              score:
                type: number
                example: 0.85
      description: Candidate languages with their associated scores
    Problem:
      type: object
      properties:
        type:
          type: string
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          format: uri
          example: https://zalando.github.io/problem/constraint-violation
          default: about:blank
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
        status:
          maximum: 600
          exclusiveMaximum: true
          minimum: 100
          type: integer
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          format: int32
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
  parameters:
    project_id:
      name: project_id
      in: path
      description: project identifier
      required: true
      schema:
        type: string
      example: dummy-fi
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Project not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'