Page Comparison

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/limitlimitmax100'
        - $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/limitnumericalIds'
        - $ref: '#/components/parameters/offsetengineIds'
      responses:         200:
 - $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'
  /groups:     getpost:
      tags:
        - GroupsEngine instances
      security:
        - bearer: [ ]
      summary: List groups Create a new engine instance
      description: |
 Returns   a collection of groups theStarts authenticateddeploying useran isengine ain memberthe ofbackground.

     parameters:   Required permissions: `MANAGE_ENGINES|SYSTEM_ADMINISTRATOR`
   - $ref: '#/components/parameters/limit'
 requestBody:
       - $ref: '#/components/parametersrequestBodies/offsetCreateEngineInstance'
      responses:
 - name: sort     202:
     in: query    description: The newly created engine instance entity schema:in the database.
          typecontent:
string             enumapplication/json:
              -schema:
name:asc               - name$ref:desc
 '#/components/schemas/EngineInstance'
     responses:   400:
     200:     $ref: '#/components/responses/400BadRequest'
    description: OK   401:
       content:   $ref: '#/components/responses/401Unauthorized'
        application/json403:
          $ref: '#/components/responses/403Forbidden'
  schema:      500:
          $ref: '#/components/schemasresponses/GroupCollection500InternalServerError'
  /engine-instances/{id}:
     401parameters:
      -    $refname: '#/components/responses/401Unauthorized'id
        403description: Engine instance ID
        $refin: '#/components/responses/403Forbidden'path
        500required: true
        schema:
   $ref: '#/components/responses/500InternalServerError'       /languagestype: integer
    get:
      tags:
        - LanguagesEngine instances
      security:
        - bearer: [ ]
      summary: ListShow languagesthe details of an engine instance
      description: |
        Returns a collection of languages used in Globalese. single engine instance.

        Required permissions: `MANAGE_ENGINES|TRANSLATE|SYSTEM_ADMINISTRATOR`

        A translation API key can also be used for authentication.
      parametersresponses:
        - $ref200:
'#/components/parameters/languageUsage'         - $refdescription: '#/components/parameters/limit'OK
         - $refcontent:
'#/components/parameters/offset'       responses:     application/json:
   200:           descriptionschema:
OK            content:    $ref: '#/components/schemas/EngineInstance'
       application/json 401:
          $ref: '#/components/responses/401Unauthorized'
  schema:      403:
          $ref: '#/components/schemasresponses/LanguageCollection403Forbidden'
        401404:
          $ref: '#/components/responses/401Unauthorized404NotFound'
        500:
          $ref: '#/components/responses/500InternalServerError'
components:   parameters:     groupIds502:
      name: group_ids   $ref: '#/components/responses/502BadGateway'
  in  delete:
query       descriptiontags:
|        - OneEngine orinstances
more  group ID(s) for filtering, comma-separated. security:
        - Examplesbearer: `1`, `1,3,5`[ ]
      schemasummary: Delete an engine instance
    oneOf  description: |
        Removes -a type:deployed integerengine instance.

        -Required typepermissions: string`MANAGE_ENGINES|SYSTEM_ADMINISTRATOR`
      styleresponses:
form        explode204:
false     languageUsage:     $ref:  name: usage'#/components/responses/204NoContent'
        in400:
query          description: |$ref: '#/components/responses/400BadRequest'
        401:
 Filter   for languages used in Globalese.  $ref: '#/components/responses/401Unauthorized'
      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:
 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:
        - enginesapplication/json:
    limit:       nameschema:
limit       in: query    $ref: '#/components/schemas/Error'
 description: |  403Forbidden:
      Limitdescription: forInsufficient results.permissions
*May* be used together with `offset`. content:
        Examplesapplication/json:
  `25`, `50`       schema:
            type$ref: integer'#/components/schemas/Error'
    offset404NotFound:
      namedescription: offsetResource not found
    in422UnprocessableEntity:
query       description: |Unprocessable entity
    500InternalServerError:
  Offset to start query from. **Must** be used together with `limit`.

  description: Internal server error while processing the request
      Examplescontent:
`50`, `100`       schemaapplication/json:
        type  schema:
integer     sourceLanguage:       name$ref: source_language'#/components/schemas/Error'
      in502BadGateway:
query       description: |Bad Gateway
  securitySchemes:
    Sourcebearer:
language.          Examplestype: `en`, `fr`http
      schemascheme:  bearer
      typedescription: stringAPI key
   targetLanguageschemas:
      name: target_languageCollectionMetadata:
      intype: queryobject
      descriptionrequired:
|        - Targetcounts
language.          Examplesproperties:
`en`, `fr`       schemacounts:
        type: string   responsestype: object
   204NoContent:       descriptionrequired:
No Content     400BadRequest:      - description:total
Bad Request       content:    - filtered
   application/json:           schemaproperties:
            $reftotal:
'#/components/schemas/Error'       401Unauthorized:       description: UnauthorizedThe total number of resources in the content:system, irrespective of any filters.
    application/json:          type: schema:integer
            $ref: '#/components/schemas/Error'
  example: 100
  403Forbidden:       description: Insufficient permissions filtered:
     content:         application/jsondescription: The number of resources in the system matching the filters.
 schema:             $reftype: '#/components/schemas/Error'integer
     404NotFound:       description: Resource notexample: found40
    422UnprocessableEntitycreatedAt:
      description: UnprocessableCreated entitytimestamp in ISO 8601 format
500InternalServerError:       descriptiontype: Internalstring
server error while processing the request example: "2017-08-30T04:34:26+00:00"
    contentdispatcherId:
        application/jsondescription: Segment-based translation dispatcher ID
      schematype: integer
      example: 1
    $refdispatcherRegion:
'#/components/schemas/Error'
    502BadGateway:    type: string
 description: Bad Gateway   securitySchemes:example: "europe-west1"
    bearerdispatcherUrl:
      type: httpstring
      schemeexample: bearer"https://dispatcher-europe-west1-ja6vheawuq-ew.a.run.app"
    Engine:
 description: API key   schemastype: object
   CollectionMetadata:   required:
   type: object    - id
 required:       - group_id
- counts       properties:- instance_ids
       counts: - name
        type: object- source_language
        - target_language
required:        - uuid
   - total  properties:
        id:
 - filtered        $ref: '#/components/schemas/engineId'
 properties:       group_id:
     total:     $ref: '#/components/schemas/groupId'
        descriptioninstance_ids:
The total number of resources in the system, irrespective of anytype: filters.array
          items:
   type: integer        $ref: '#/components/schemas/numericalId'
     example: 100  name:
          filteredtype: string
          example: Engine 1
description: The number of resources in the system matchingsource_language:
the filters.         $ref: '#/components/schemas/sourceLanguage'
    type: integer   target_language:
           example$ref: 40'#/components/schemas/targetLanguage'
    dispatcherUrl:    uuid:
  type: string       example$ref: "https:'#//dispatcher-europe-west1-ja6vheawuq-ew.a.run.app"components/schemas/engineUuid'
    EngineEngineCollection:
      type: object
      required:
        - iddata
        - group_id meta
      properties:
        data:
        - instance_ids type: array
      - name   items:
     - source_language      $ref: '#/components/schemas/Engine'
 - target_language      meta:
  - uuid       properties$ref: '#/components/schemas/CollectionMetadata'
    engineId:
       iddescription: Engine ID
        $reftype: '#/components/schemas/engineId'integer
      example: 10
group_id:    EngineInstance:
      $reftype: '#/components/schemas/groupId'object
        instance_ids:required:
        - id
 type: array      - engine_id
   items:     - dispatcher_url
      $ref: '#/components/schemas/numericalId'
  - status
      nameproperties:
          typeid:
string           example$ref: Engine 1 '#/components/schemas/numericalId'
        sourceengine_languageid:
          $ref: '#/components/schemas/sourceLanguageengineId'
        targetdispatcher_languageurl:
          $ref: '#/components/schemas/targetLanguagedispatcherUrl'
        uuidstatus:
          $ref: '#/components/schemas/engineUuidengineInstanceStatus'
    EngineCollectionEngineInstanceCollection:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EngineEngineInstance'
        meta:
          $ref: '#/components/schemas/CollectionMetadata'
    engineInstanceStatus:
      type: string
   engineId:
   enum:
        - deploying
        - error_removal_engine_manager_internal_error
     description: Engine ID - error_removal_engine_manager_rejected_request
    type: integer   - error_removal
  example: 10     EngineInstance:- on
     type: object  - queued
   required:     - removing
  - id engineUuid:
      type: -string
engine_id      example: "21cfda50-1944-46fc-901c-04a168ea6fee"
 - dispatcher_url  Error:
      -type: statusobject
      properties:
        iderror:
          $reftype: '#/components/schemas/numericalId'string
        engine_id:  example: "Error message."
      $refrequired:
'#/components/schemas/engineId'        - error
dispatcher_url:    Group:
      $reftype: '#/components/schemas/dispatcherUrl'object
      required:
  status:      - id
   $ref: '#/components/schemas/engineInstanceStatus'    - EngineInstanceCollection:name
      typeproperties:
object        requiredid:
        - data    $ref: '#/components/schemas/groupId'
    - meta   name:
   properties:       type: string
data:          example: type:Default
array    GroupCollection:
      itemstype: object
      required:
    $ref: '#/components/schemas/EngineInstance'   - data
    meta:  properties:
        $ref: '#/components/schemas/CollectionMetadata'data:
    engineInstanceStatus:       type: stringarray
      enum:    items:
    - deploying         - error_removal_engine_manager_internal_error$ref: '#/components/schemas/Group'
    groupId:
   - error_removal_engine_manager_rejected_request  description: Group ID
    - error_removal type: integer
      -example: on2
    Language:
   - queued  type: object
     - removingrequired:
    engineUuid:    - id
 type: string    properties:
  example: "21cfda50-1944-46fc-901c-04a168ea6fee"     Errorid:
      type: object   type: string
  properties:        example: en-us
error:    LanguageCollection:
      type: stringobject
      required:
   example: "Error message."   - data
  required:      - meta
 - error    properties:
Group:        typedata:
object       required:   type: array
    -  id    items:
    - name       properties$ref: '#/components/schemas/Language'
       id meta:
          $ref: '#/components/schemas/groupIdCollectionMetadata'
    numericalId:
   name:   description: ID
      type: stringinteger
      example: 10
    exampleRemoteDispatcherCollection:
Default      GroupCollectiontype: object
     type required:
 object       required:- data
        - datameta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GroupRemoteDispatcher'
    groupId:    meta:
         description $ref: Group ID'#/components/schemas/CollectionMetadata'
    RemoteDispatcher:
      type: integerobject
      example: 2required:
        - id
        - region
        - url
Language:        type:- objecttimestamps
      requiredproperties:
        id:
  - id       properties:$ref: '#/components/schemas/dispatcherId'
        idregion:
          type$ref: string'#/components/schemas/dispatcherRegion'
        url:
  example: en-us        LanguageCollection$ref: '#/components/schemas/dispatcherUrl'
     type: object  timestamps:
    required:      $ref: '#/components/schemas/RemoteDispatcherTimestamps'
 - data  RemoteDispatcherTimestamps:
      -type: metaobject
      propertiesrequired:
        - created_at
data:        - updated_at
 type: array    properties:
      items:  created_at:
          $ref: '#/components/schemas/LanguagecreatedAt'
        metaupdated_at:
          $ref: '#/components/schemas/CollectionMetadataupdatedAt'
    numericalIdsourceLanguage:
      description: Source IDlanguage code
      type: integerstring
      example: 10en-us
    sourceLanguagetargetLanguage:
      description: SourceTarget language code
      type: string
      example: en-usit
    targetLanguageupdatedAt:
      description: Target language codeUpdated timestamp in ISO 8601 format
      type: string
      nullable: true
      example: it"2017-08-30T04:34:26+00:00"