Page Comparison

This documentation is incomplete. New endpoints will continue be published from time to time.

openapi: 3.0.2
servers: []
info:
  title: Globalese
  version: "3-beta"
  description: Globalese API v3 beta
tags:
  - name: Engines
  - name: Engine instances
  - name: Groups
  - name: Languages
  - name: Segment translation dispatchers
paths:
  /engines:
    get:
      tags:
        - Engines
      security:
        - bearer: [ ]
      summary: List engines
      description: |
        Returns a collection of engines.

        A translation API key can also be used for authentication.
      parameters:
        - $ref: '#/components/parameters/limitmax100'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sourceLanguage'
        - $ref: '#/components/parameters/targetLanguage'
        - $ref: '#/components/parameters/groupIds'
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - name:asc
              - name:desc
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineCollection'
        401:
          $ref: '#/components/responses/401Unauthorized'
        500:
          $ref: '#/components/responses/500InternalServerError'
  /engine-instances:
    get:
      tags:
        - Engine instances
      security:
        - bearer: [ ]
      summary: List engine instances
      description: |
        Returns a collection of engine instances (being) deployed.

        Required permissions: `MANAGE_ENGINES|TRANSLATE|SYSTEM_ADMINISTRATOR`

        A translation API key can also be used for authentication.
      parameters:
        - $ref: '#/components/parameters/numericalIds'
        - $ref: '#/components/parameters/engineIds'
        - $ref: '#/components/parameters/groupIds'
        - $ref: '#/components/parameters/limitmax100'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineInstanceCollection'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        500:
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
        - Engine instances
      security:
        - bearer: [ ]
      summary: Create a new engine instance
      description: |
        Starts deploying an engine in the background.

        Required permissions: `MANAGE_ENGINES|SYSTEM_ADMINISTRATOR`
      requestBody:
        $ref: '#/components/requestBodies/CreateEngineInstance'
      responses:
        202:
          description: The newly created engine instance entity in the database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineInstance'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        500:
          $ref: '#/components/responses/500InternalServerError'
  /engine-instances/{id}:
    parameters:
      - name: id
        description: Engine instance ID
        in: path
        required: true
        schema:
          type: integer
    get:
      tags:
        - Engine instances
      security:
        - bearer: [ ]
      summary: Show the details of an engine instance
      description: |
        Returns a single engine instance.

        Required permissions: `MANAGE_ENGINES|TRANSLATE|SYSTEM_ADMINISTRATOR`

        A translation API key can also be used for authentication.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngineInstance'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        404:
          $ref: '#/components/responses/404NotFound'
        500:
          $ref: '#/components/responses/500InternalServerError'
        502:
          $ref: '#/components/responses/502BadGateway'
    delete:
      tags:
        - Engine instances
      security:
        - bearer: [ ]
      summary: Delete an engine instance
      description: |
        Removes a deployed engine instance.

        Required permissions: `MANAGE_ENGINES|SYSTEM_ADMINISTRATOR`
      responses:
        204:
          $ref: '#/components/responses/204NoContent'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        404:
          $ref: '#/components/responses/404NotFound'
        500:
          $ref: '#/components/responses/500InternalServerError'
        502:
          $ref: '#/components/responses/502BadGateway'
  /groups:
    get:
      tags:
        - Groups
      security:
        - bearer: [ ]
      summary: List groups
      description: Returns a collection of groups the authenticated user is a member of.
      parameters:
        - $ref: '#/components/parameters/limitmax100'
        - $ref: '#/components/parameters/offset'
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - name:asc
              - name:desc
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupCollection'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        500:
          $ref: '#/components/responses/500InternalServerError'
  /languages:
    get:
      tags:
        - Languages
      security:
        - bearer: [ ]
      summary: List languages
      description: |
        Returns a collection of languages used in Globalese.

        A translation API key can also be used for authentication.
      parameters:
        - $ref: '#/components/parameters/languageUsage'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageCollection'
        401:
          $ref: '#/components/responses/401Unauthorized'
        500:
          $ref: '#/components/responses/500InternalServerError'
  /segment-translation-dispatchers:
    get:
      tags:
        - Segment translation dispatchers
      security:
        - bearer: [ ]
      summary: List segment translation dispatchers
      description: |
        Required permissions: `MANAGE_ENGINES|SYSTEM_ADMINISTRATOR`
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoteDispatcherCollection'
        401:
          $ref: '#/components/responses/401Unauthorized'
        403:
          $ref: '#/components/responses/403Forbidden'
        500:
          $ref: '#/components/responses/500InternalServerError'
        502:
          $ref: '#/components/responses/502BadGateway'
components:
  parameters:
    engineIds:
      name: engine_ids
      in: query
      description: |
        One or more engine ID(s) for filtering, comma-separated.

        Examples: `1`, `1,3,5`
      schema:
        oneOf:
          - type: integer
          - type: string
    groupIds:
      name: group_ids
      in: query
      description: |
        One or more group ID(s) for filtering, comma-separated.

        Examples: `1`, `1,3,5`
      schema:
        oneOf:
          - type: integer
          - type: string
      style: form
      explode: false
    languageUsage:
      name: usage
      in: query
      description: |
        Filter for languages used in Globalese.

        Optionally, the `:source` or `:target` modifier may be appended to the parameter value to filter for languages used on the source or target language side only.

        `usage=engines:source` will return a list of languages used as engine source languages.

        `usage=engines` will return a list of languages used as engine languages, either source or target.
      schema:
        type: string
        enum:
          - engines
    limit:
      name: limit
      in: query
      description: |
        Limit for results. *May* be used together with `offset`.

        Examples: `25`, `50`
      schema:
        type: integer
    limitmax100:
      name: limit
      in: query
      description: |
        Limit for results. It cannot be greater than 100. *May* be used together with `offset`.

        Examples: `25`, `50`

        If not provided, it will automatically be set to 100.
      schema:
        type: integer
    numericalIds:
      name: ids
      in: query
      description: |
        One or more ID(s) for filtering, comma-separated.

        Examples: `3`, `3,4`
      schema:
        type: string
      style: form
      explode: false
    offset:
      name: offset
      in: query
      description: |
        Offset to start query from. **Must** be used together with `limit`.

        Examples: `50`, `100`
      schema:
        type: integer
    sourceLanguage:
      name: source_language
      in: query
      description: |
        Source language.

        Examples: `en`, `fr`
      schema:
        type: string
    targetLanguage:
      name: target_language
      in: query
      description: |
        Target language.

        Examples: `en`, `fr`
      schema:
        type: string
  requestBodies:
    CreateEngineInstance:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - engine_id
              - dispatcher_id
            properties:
              engine_id:
                $ref: '#/components/schemas/engineId'
              dispatcher_id:
                $ref: '#/components/schemas/dispatcherId'
  responses:
    204NoContent:
      description: No Content
    400BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    403Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    404NotFound:
      description: Resource not found
    422UnprocessableEntity:
      description: Unprocessable entity
    500InternalServerError:
      description: Internal server error while processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    502BadGateway:
      description: Bad Gateway
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key
  schemas:
    CollectionMetadata:
      type: object
      required:
        - counts
      properties:
        counts:
          type: object
          required:
            - total
            - filtered
          properties:
            total:
              description: The total number of resources in the system, irrespective of any filters.
              type: integer
              example: 100
            filtered:
              description: The number of resources in the system matching the filters.
              type: integer
              example: 40
    createdAt:
      description: Created timestamp in ISO 8601 format
      type: string
      example: "2017-08-30T04:34:26+00:00"
    dispatcherId:
      description: Segment-based translation dispatcher ID
      type: integer
      example: 1
    dispatcherRegion:
      type: string
      example: "europe-west1"
    dispatcherUrl:
      type: string
      example: "https://dispatcher-europe-west1-ja6vheawuq-ew.a.run.app"
    Engine:
      type: object
      required:
        - id
        - group_id
        - instance_ids
        - name
        - source_language
        - target_language
        - uuid
      properties:
        id:
          $ref: '#/components/schemas/engineId'
        group_id:
          $ref: '#/components/schemas/groupId'
        instance_ids:
          type: array
          items:
            $ref: '#/components/schemas/numericalId'
        name:
          type: string
          example: Engine 1
        source_language:
          $ref: '#/components/schemas/sourceLanguage'
        target_language:
          $ref: '#/components/schemas/targetLanguage'
        uuid:
          $ref: '#/components/schemas/engineUuid'
    EngineCollection:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Engine'
        meta:
          $ref: '#/components/schemas/CollectionMetadata'
    engineId:
      description: Engine ID
      type: integer
      example: 10
    EngineInstance:
      type: object
      required:
        - id
        - engine_id
        - dispatcher_url
        - status
      properties:
        id:
          $ref: '#/components/schemas/numericalId'
        engine_id:
          $ref: '#/components/schemas/engineId'
        dispatcher_url:
          $ref: '#/components/schemas/dispatcherUrl'
        status:
          $ref: '#/components/schemas/engineInstanceStatus'
    EngineInstanceCollection:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EngineInstance'
        meta:
          $ref: '#/components/schemas/CollectionMetadata'
    engineInstanceStatus:
      type: string
      enum:
        - deploying
        - error_removal_engine_manager_internal_error
        - error_removal_engine_manager_rejected_request
        - error_removal
        - on
        - queued
        - removing
    engineUuid:
      type: string
      example: "21cfda50-1944-46fc-901c-04a168ea6fee"
    Error:
      type: object
      properties:
        error:
          type: string
          example: "Error message."
      required:
        - error
    Group:
      type: object
      required:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/groupId'
        name:
          type: string
          example: Default
    GroupCollection:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Group'
    groupId:
      description: Group ID
      type: integer
      example: 2
    Language:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: en-us
    LanguageCollection:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Language'
        meta:
          $ref: '#/components/schemas/CollectionMetadata'
    numericalId:
      description: ID
      type: integer
      example: 10
    RemoteDispatcherCollection:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RemoteDispatcher'
        meta:
          $ref: '#/components/schemas/CollectionMetadata'
    RemoteDispatcher:
      type: object
      required:
        - id
        - region
        - url
        - timestamps
      properties:
        id:
          $ref: '#/components/schemas/dispatcherId'
        region:
          $ref: '#/components/schemas/dispatcherRegion'
        url:
          $ref: '#/components/schemas/dispatcherUrl'
        timestamps:
          $ref: '#/components/schemas/RemoteDispatcherTimestamps'
    RemoteDispatcherTimestamps:
      type: object
      required:
        - created_at
        - updated_at
      properties:
        created_at:
          $ref: '#/components/schemas/createdAt'
        updated_at:
          $ref: '#/components/schemas/updatedAt'
    sourceLanguage:
      description: Source language code
      type: string
      example: en-us
    targetLanguage:
      description: Target language code
      type: string
      example: it
    updatedAt:
      description: Updated timestamp in ISO 8601 format
      type: string
      nullable: true
      example: "2017-08-30T04:34:26+00:00"