openapi.yaml

openapi: '3.0.2'
info:
  title: Apertium Stats Service
  version: '0.1.0'
  description: Stateful Rust web service that enables the efficient concurrent compilation
    and distribution of statistics regarding Apertium packages via a RESTful API.
servers:
  - url: https://apertium.org/stats-service
    description: Production
  - url: http://localhost:8000
    description: Development
paths:
  /:
    get:
      summary: Returns usage instructions
      responses:
        '200':
            description: Usage instructions
            content:
              text/plain: {}
  /{package}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/Recursive'
      - $ref: '#/components/parameters/Async'
    get:
      summary: Returns statistics for the specified package
      responses:
        '200':
          $ref: '#components/responses/Stats'
        '202':
          $ref: '#components/responses/StatsInProgress'
        '429':
          $ref: '#components/responses/StatsAlreadyInProgress'
        '400':
          $ref: '#components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/PackageNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Computes statistics for the specified package
      responses:
        '202':
          $ref: '#components/responses/StatsInProgress'
        '429':
          $ref: '#components/responses/StatsAlreadyInProgress'
        '400':
          $ref: '#components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{package}/{kind}:
    parameters:
      - $ref: '#/components/parameters/Package'
      - $ref: '#/components/parameters/Kind'
      - $ref: '#/components/parameters/Recursive'
      - $ref: '#/components/parameters/Async'
    get:
      summary: Returns statistics of the specified kind for the specified package
      responses:
        '200':
          $ref: '#components/responses/Stats'
        '202':
          $ref: '#components/responses/StatsInProgress'
        '429':
          $ref: '#components/responses/StatsAlreadyInProgress'
        '400':
          $ref: '#components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/PackageNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Computes statistics of the specified kind for the specified package
      responses:
        '202':
          $ref: '#components/responses/StatsInProgress'
        '429':
          $ref: '#components/responses/StatsAlreadyInProgress'
        '400':
          $ref: '#components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /packages:
    get:
      summary: Returns listing of packages
      responses:
        '200':
          $ref: '#components/responses/Packages'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Updates package cache and returns updated listing
      responses:
        '200':
          $ref: '#components/responses/Packages'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /packages/{query}:
    parameters:
      Query:
        name: query
        in: path
        required: false
        description: search string for case-insensitive package name filtering
        example: eng
        schema:
          type: string
    get:
      summary: Returns listing of packages filtered by query
      responses:
        '200':
          $ref: '#components/responses/Packages'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Updates cache of packages and returns updated listing filtered by query
      responses:
        '200':
          $ref: '#components/responses/Packages'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Stats:
      description: Package statistics
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
              stats:
                $ref: '#/components/schemas/Stats'
              in_progress:
                $ref: '#/components/schemas/StatsInProgress'
    StatsInProgress:
      description: Package statistics in progress
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                example: apertium-pl-dsb
                type: string
              in_progress:
                $ref: '#/components/schemas/StatsInProgress'
    StatsAlreadyInProgress:
      description: Package statistics already in progress
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                example: apertium-pl-dsb
                type: string
              in_progress:
                $ref: '#/components/schemas/StatsInProgress'
    Packages:
      description: Package metadata
      content:
        application/json:
          schema:
            type: object
            properties:
              as_of:
                $ref: '#/components/schemas/DateTime'
              next_update:
                $ref: '#/components/schemas/DateTime'
              packages:
                type: array
                items:
                  $ref: '#/components/schemas/Package'
    BadRequestError:
      description: Bad request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PackageNotFoundError:
      description: Package not found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
  parameters:
    Package:
      name: package
      in: path
      required: true
      description: package identifier
      example: apertium-pl-dsb
      schema:
        type: string
    Kind:
      name: kind
      in: kind
      required: true
      description: file kind identifier
      example: bidix
      schema:
        type: string
    Recursive:
      name: recursive
      in: query
      description: whether file search should be recursive
      schema:
        type: boolean
        default: false
    Async:
      name: async
      in: query
      description: whether statistics compilation should be asynchronous
      schema:
        type: boolean
        default: true
  schemas:
    Sha:
      type: string
      example: 9f09e5e37aadb005fbd420e79803e506a8202f73
    DateTime:
      type: string
      format: date-time
      example: '2018-12-08T01:14:30.363888593'
    Actor:
      type: object
      properties:
        name:
          type: string
          example: sushain97
        email:
          type: string
          format: email
          example: sushain@skc.name
    Error:
      type: object
      properties:
        name:
          example: apertium-pl-dsb
          type: string
        error:
          example: No recognized files
          type: string
    StatKind:
      type: string
      enum:
        - Entries
        - Paradigms
        - Rules
        - Macros
        - Stems
        - VanillaStems
        - Lexicons
        - LexiconEntries
        - Patterns
        - PatternEntries
    FileKind:
      type: string
      enum:
        - Monodix
        - Bidix
        - MetaMonodix
        - MetaBidix
        - Postdix
        - Rlx
        - Transfer
        - Lexc
        - Twol
        - Lexd
    File:
      type: object
      properties:
        last_author:
          type: string
          example: jim.o.regan
        size:
          type: integer
          example: 13
        last_changed:
          $ref: '#components/schemas/DateTime'
        path:
          type: string
          example: apertium-pl-dsb.pl-dsb.dix
        revision:
          type: integer
          example: 13
        sha:
          $ref: '#components/schemas/Sha'
    Stats:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/File'
          - type: object
            properties:
              name:
                type: string
                example: apertium-pl-dsb
              file_kind:
                $ref: '#components/schemas/FileKind'
                example: stems
              stat_kind:
                $ref: '#components/schemas/StatKind'
                example: rlx
              value:
                example: 366
              created:
                $ref: '#components/schemas/DateTime'
              requested:
                $ref: '#components/schemas/DateTime'
    StatsInProgress:
      type: array
      items:
        type: object
        properties:
          file:
            $ref: '#/components/schemas/File'
          kind:
            $ref: '#components/schemas/FileKind'
          created:
            $ref: '#components/schemas/DateTime'
    Commit:
      type: object
      properties:
        message:
          type: string
          example: more words, some weird spellrelax
        sha:
          $ref: '#components/schemas/Sha'
        authored:
          $ref: '#components/schemas/DateTime'
        committed:
          $ref: '#components/schemas/DateTime'
        author:
          $ref: '#components/schemas/Actor'
        committer:
          $ref: '#components/schemas/Actor'
    Package:
      type: object
      properties:
        description:
          type: string
          example: Apertium linguistic data for English
        name:
          type: string
          example: apertium-eng
        topics:
          type: array
          items:
            type: string
            example: apertium-languages
        last_commit:
          $ref: '#components/schemas/Commit'