API Access

API Access

External programs, legacy systems, programmers using console or API clients can access the full solution functionalities using the generic APIs.

The updated description of APIs can be found at the following repositories:

• https://corporateapi2.docs.apiary.io/# (text processing),

• https://pgfile.docs.apiary.io/# (document processing) and

• http://prodb.pangeamt.com:8000/docs (anonymization)

• Pecat API (no online repo)

Pangeanic’s API is a simple RESTFul implementation where typically the requests are sent as POSTs with a json encoded body.

When handling files the content is sent or received in base-64 encoded form.

As an example, the API definition for the translation of a single sentence would be:


POST to endpoint: https://production_access_server_url:8080/NexRelay/v1/translate


Headers: Content-Type : application/json

Request Body: { "src":"en",
"tgt":"es",
"apikey":"your_api_key",
"engineid":"your_engine_id",
"text":[
"This is an example." ] }
Answer Body: [ [ { "src": "This is an example.", "tgt": "Esto es un ejemplo." } ]

Both https and http endpoints are configurable in the Access Server.

Text Processing API

HOST: http://prod.pangeamt.com:8080/NexRelay/v1/

List Engines [/corp/engines]

1. 1. 1. List All available engines [POST]

This edpoint is required to list the list of IDs of the available engines fo your APIKey

+ Request (application/json)

{

   "apikey": "your-apikey-here"

}

+ Response 200 (application/json)

{

  "engines": [

         {
            "id": 1,
             
            "processid": 1,
            "serviceid": 1,
            "inserviceid": 0,
            "src": "en",
            "tgt": "es",
            "descr": "ENES_B_plain", 
            "domain": "",
            "flavor": "",
            "status": 0 
             },
            {
               "id": 2,
               "processid": 1,
               "serviceid": 2,
               "inserviceid": 0,
               "src": "es",
               "tgt": "en",
               "descr": "ESEN_generic",
               "domain": "",
               "flavor": "",
               "status": 0

                             }
                       }

                }




Process text [/translate]

1. 1. 1. Process a text segment [POST]

A text segment is a number of words, processing works best if the segment is a sentence with whole semantic content.

- src and tgt are 2-letter language codes

- engine is the id (string) of the engine to be used

- glossary_id, optional, is the id (integer) of the glossary to be used

+ Request (application/json)

 {

   "src":"es",
   "tgt":"en",
   "apikey":"your-api-key-here",
   "engine":"2",
   "glossary_id": 1,
   "text":[
   "¿Cómo estás?",
   "Mi perro es negro"
 ]

}

+ Response 200 (application/json)

[

 [
   {
      "src": "¿Cómo estás?",
      "tgt": "How are you?"
   }
 ],
 [
  {

     "src": "Mi perro es negro",
     "tgt": "My dog is black"
   }

  ]
 ]

Document Processing API

HOST: http://prod.pangeamt.com:8080/PGFile/v1

File Uploading [/sendfile]

1. 1. 1. Send a File [POST]

Main request. Send a file to the service for translation.

The process parameters have to be included

The success response is a json with file guid.

+ Request

=multipart/form-data;boundary=----WebKitFormBoundary8M3sSU13ul5lXSJm)

---

WebKitFormBoundary8M3sSU13ul5lXSJm

        Content-Disposition: form-data; name="json"

    {

"title":"filename.docx", "processname":"translation", "engine":"123", "src":"es", "tgt": "en" , "apikey":"your-apikey-here", "username": "testuser", "notiflink": "testlink", "processoption": "1" }

---

WebKitFormBoundary8M3sSU13ul5lXSJm

Content-Disposition: form-data; name="file"; filename="filename.docx" Content-Type: application/vnd.openxmlformats- officedocument.wordprocessingml.document data

---

WebKitFormBoundary8M3sSU13ul5lXSJm--

+ Response 200 (application/json)

{

"fileId": "8d4e1c5be60d4e04850f55ec135f2554"

}

+ Response 500 (application/json)

{ "error": true, "error_message" : "the-error-message" }

Checking file status [/checkfile?apikey&fileid] Use /checkfile to get the processing status of a file, this is a json post where body can have three forms:

- just the apikey, the response will return info about all files being processed for the apikey.

- guid, to get info about a single file

Use a get request like:

https://server_address:server_port/PGFile/v1/checkfile?apikey=your_api_key
https://server_address:server_port/PGFile/v1/checkfile?apikey=your_api_key&guid=d9b95ffb3bc347efa6a7cb90ca80ca74

The returned answer is a json list containing one json object for every file.

The important field returned for every file is the status, an integer with possible values

- 10, file is queued for process at the server - 6 or 7, file is being analyzed - 20, 30 or 40, file is being processed - 100, file processed successsfully, waiting download - 110 or 120, file downloaded - -10 or -20 (negative values), processing error

1. 1. 1. Check the processing status of a file [GET]

+ Response 200 (application/json)

  [

{ "fileId": "1dc77dc5ba6d44828b860537dae07187", "translatedPath": None, "engineId": 58, "glossaryId": 0, "src": "es", "tgt": "en", "isZip": False, "ztot": 0, "zfinished": 0, "translatedName": None, "processName": "translate", "processOptionId": 1, "link": "", "status": 10, "id": 16567, "fileName": "test.txt"

 }

]

## Checking and downloading file [/retrievefile]

This is a POST request that can be used to get info about a file that is being processed and download the processed file is process has finished.

• • WARNING** this endpoint is NOT safe for very big files: the file is returned in base64

encoding and requires a lot of memory at server and client side.

When file is finished a 200 response is returned with the file. If file is in processs a 200 response is returned with the status data.

Errors will generate a 401 response.

1. 1. 1. Check and get File [POST]

+ Request (application/json)

{ "apikey": "your-api-key-here", "guid": "1dc77dc5ba6d44828b860537dae07187" }

+ Response 200 (application/json)

1. response when file is not finished

{ "success": True, "error": {}, "status": "10", "data": {} }

# response when file is finished

{ "success": True, "error": {}, "status": "110", "data": { "guid": "d74b06fd52434ad2bfbe82ebbff96464", "fileType": "txt", "filename": "test.txt", "file": "U2VlIHRoaW5ncyB0byBkbywgcmVzdGF1cmFudHMsIGFuZCBob3RlbHMNCg==" } }

+ Response 401 (application/json)

{ "success": False, "error": { "statusCode": 401, "code": 6, "message": "Invalid GUID" }, "data": {} }

Downloading file [/download?apikey&fileid]

Simple get request to retrieve a file. The get parameters are:

- apikey - fileid, the file GUID

The file is returned as a stream (similar to a call to wget)

1. 1. 1. Send a File [GET]

+ Response 200

Anonymize a file [/anonymize/xliff]

1. 1. 1. Anonymize a file [POST]

Main request. Send an XLIFF file to the service for anonimization.

Anonymize an XLIFF(XML Localization Interchange File Format) file. The request body must be Content-Type multipart/form-data

1. noqa Args:

• anon_dict: TAGs, entities pairs that should be anonymized.
• clear_list: entities that should not be anonymized
• model: pre-trained model to use, default ner-fast
• lang: language of the XLIFF file, default en_US.UTF-8 Please refer to default.json file for more info # noqa Returns: A dictionary with the

following keys:

• status: true or false,
• message: the NN response of the anonimization process.
• anon_sentence: If status is true, contains the anonymized sentence with

the entities recognized between brackets. # noqa

Example body payload: { "model_lang": "en", "anon_dict": [ { "entity": "string", "name": "string", "path": "string" } ], "clear_list": [ "string" ], "anon_list_tagset": [], "sensibility": 0, "mask": "TAG:idx", "profile_id": 1, "sentence": "string" } Responses Code: 200, returns anonymized sentence Code 500, validation error, returns:

{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] }

Pecat API

Database Schema

Constants used when using the API

Projects

Status of a project

  PROJECT_CREATED = 0 //the project was created successfully

  PROJECT_PREPARING = 2 // preparation has started, bundling and assigning is possible

  PROJECT_PREPARED = 3 // project fully prepared, translations can start

working

  PROJECT_WIP = 4 // project progressing

  PROJECT_DONE = 5 // project finished, no more translation, revision or eval required

  PROJECT_CLOSED = 6; // no further actions allowed, except OPEN
 
  PROJECT_ARCHIVED = 100 // not visible in normal lists

Jobs

job types

 0: translation

 1: revision

 2: evaluation

translation types

  0: simple

  1: double, with alternative

Preparation status values

JOB_PREPSTATUS_CREATED = 0 // job defined, TUs loading in tables

JOB_PREPSTATUS_LOADED = 1 //TUs loaded, job can be prepared, bundling possible

JOB_PREPSTATUS_PREPAREREQUESTED = 2 //PM has requested preparation

JOB_PREPSTATUS_PREPARING = 3 // job being prepared

JOB_PREPSTATUS_PREPARED = 4 // job fully prepared

Status values , for every job two status are always kept for worse & best status of the included TUs/Bundles

JOB_STATUS_ERROR = -1 // Job failed loading or preparing

JOB_STATUS_CREATED = 0 // Job successfully created

JOB_STATUS_LOADED = 1 // Job TUs loaded

JOB_STATUS_PREPARING = 2 // Job being prepared

JOB_STATUS_UNBUNDLED = 3 // Job requiring bundling, some TUs not bundled

JOB_STATUS_BUNDLED = 4 // TUs bundled

JOB_STATUS_ASSIGNED = 5 // bundles assigned

JOB_STATUS_TRANSLATING = 6 // bundles translating

JOB_STATUS_EVALUATING = 7 //TUs being evaluated

JOB_STATUS_TRANSLATED = 8 // All TUs translated

JOB_STATUS_DELIVERING = 9 // Deliveries done

JOB_STATUS_DONE = 10 // Job finished

Bundles

   Budnle Type
   
     0: translation
     1: revision
     2: evaluation

   Bundle extraction mode

     0: consecutive
     1: hashed

   Bundle Status values

      BUNDLE_STATUS_ERROR = -1
      BUNDLE_STATUS_CREATED = 0
      BUNDLE_STATUS_PREPARING = 1
      BUNDLE_STATUS_PREPARED = 2
      BUNDLE_STATUS_ASSIGNED = 3
      BUNDLE_STATUS_WIP = 4
   
    
      BUNDLE_STATUS_TRANSLATING = 5 // Some TUs require translation,all evaluation done
      BUNDLE_STATUS_TRANSLATINGANDEVALUATING = 6
      BUNDLE_STATUS_EVALUATING = 7 // No more translation required
      BUNDLE_STATUS_DONE = 8
      BUNDLE_STATUS_FREED = 9 //can be delivered if not empty!
      BUNDLE_STATUS_DELIVERED = 10

        Qamode how translation and QA are linked

        0:   default, synch qa // the translator receives QA check synchronously after validation of a translation

        1: asynch qa // QA triggers but result is sent to translator asynchronously

        2: no QA // No QA is done after translation validation

       Qemode, how evaluation for the bundle is defined

            0: default, 10% early and last weight
            1: 10% evenly distributed
            2: 5% evenly distributed
            3: No QE

        Freemode, how a bundle is unassigned when PM requests it

         0: free all tus, reset translations, QA and evaluations
         1: free not QAed tus, keep translations, QA and QE

        Activity bundle status,

            0: Normal, translations and evaluation are accepted
            1: Paused, PM has decided not more work can be done for the time being

TUs constants

Translation code, reasons for a source not to be translated

         0:Translatable, no reason to skip translation
         1: Nonsense
         2: Encoding
         3: Source not in the right language
         4: Other
         5:Not-alternative possible (used in alt translations)
  

Translation status , applied to main and alternative transations

     0:Translation required
     1: Translation done

Qastatus , how QA is for a TU

     0: Not doable yet
     1: QA required
     2: QA to validate
     3:QA validated, false positive
     4: QA ok
     5: QA ko

Qestatus, how QE is for a TU. When bundling some TUs are randomly selected for QE

   0: Not candidate for QE
   1: QE candidate, pending evaluation
   2: QE done, positive
   3: QE done, negative

TU Status

TU_STATUS_CREATED = 0 //no translation has been done TU_STATUS_PREPARED = 1 //TU prepared TU_STATUS_TRANSLATED = 2 //translation finished TU_STATUS_QAED = 3 //QA finished TU_STATUS_QED = 4 //QA evaluated TU_STATUS_DONE = 5 // No more work required TU_STATUS_REWORK = 6 // like CREATED, after some work has been done TU_STATUS_FREED = 7 // like CREATED, after translator has been unassigned

    REVISION STATUS

       TU_REVSTATUS_NOTDOABLE = 0; //initial status
       TU_REVSTATUS_REQUIRED = 1; //un-used
       TU_REVSTATUS_OK = 2; //revision done, translation accepted
       TU_REVSTATUS_UPDATED = 3; //revision done, translation was changed
       TU_REVSTATUS_KO = 4; //translation not accepted, re-do
       TU_REVSTATUS_PENDING = 5; //revision bookmarked by reviewer for later
     

TU_REVSTATUS_SKIPPED = 6; //the revision will not be done

   QE constants
   Eval Types

   0: Accuracy
   1:Fluency
   2: Terminology
   3: Style
   4: Locale
   5: Instructions
   6: Other

Eval SubTypes

0: Under-translation 1: Untranslated text

Eval Criticity

0: Preferential 1: Minor 2: Major 3: Critical

Bundle-TU relation

Status

0: Normal 1: Old // TU belonged to this bundle but was unassigned

Deliveries

  Delivery Type
     
      0: Partial
      1: Final

  Delivry Mode

0: standard (all QAed TUs of bundles whose QEScore > 90)

1: fine (Only TUs which idinbundle< smallest badQE)

2: unconditional (all QAEd TUs)

5: Emergency (All TUs, use pretrans if not translated)

Status Values

-1: error

0: requested

1: preparing

2: Done

  Endpoints

  Production URL: http://prod.pangeamt.com:8080/PGWF/v1

       Requests are in all cases application/json and the Content-Type header should be sent. Except the /addjob request which is form-data to be able to send large files.
     
        Responses are always json format.

        /projects

       Get the list of all projects with data required to show lists. An array is returned containing the project data and the current kpi/counters values

       GET
        Body: none
        Response:

[ { "id": 1,

"name": "Project1",

"descr": "P1 description",

"customerid": 2,

"pmid": 1,

"status": 1,

"statusmsg": “Loaded”,

"kpis": {

"tus": 101576,

"preparedtus": 0,

"bundledtus": 0,

"assignedtus": 0,

"translatedtus": 0,

"untranslatedtus": 0,

"unalttranslatedtus": 0,

"QAedTus": 0,

"QAposTus": 0,

"QAnegTus": 0,

"QAFPTus": 0,

"QEplannedTus": 0,

"QEposTus": 0,

"QEnegTus": 0,

"QEScore": 0, "progress": 0, "jobs": 11 } }, { "id": 2,

"name": "Project4",

"descr": "P4 description",

"customerid": 4,

"pmid": 5,

"status": 0,

"statusmsg": “Created”,

"kpis": {

"tus": 101576,

"preparedtus": 0,

"bundledtus": 0,

"assignedtus": 0,

"translatedtus": 0,

"untranslatedtus": 0,

"unalttranslatedtus": 0,

"QAedTus": 0,

"QAposTus": 0,

"QAnegTus": 0,

"QAFPTus": 0,

"QEplannedTus": 0,

"QEposTus": 0,

"QEnegTus": 0,

"QEScore": 0,

"progress": 0,

"jobs": 11

}
}

] /addproject Create a new project. Name and customerid are mandatory, PMid is optional, can be set later. The response contains the id of new project, and 0 if the process failed. POST

Body;

{ "name":"PxProject",

"descr":"Description of the project",

"customerid":1,

"pmid":2 //optional

}

Response: { "projectid": 3 }

/archiveproject

Moves all project assets to archive (project, jobs, bundle, tus and relations). Archived projects can only be deleted or un-archived.

POST

Body: { "id": 4, } Response:

{ "rc": 0 //0 if no error! }

/delproject

Deletes a project, its jobs, tus and bundles. This process cannot be undone, all references to the project, jobs, bundles and tus are deleted in the database and cannot be recovered. POST Body:

{ "id": 4,

}

{

"rc": 0 //0 if no error!

}

/editproject Change existing project values. The body can contain any combination of new values and only the id to identify the project is required. Change of status might interfere with the internal dynamic of status propagation POST Body: { "id": 4,

"name":"PxProject4", //opt

"descr":"PPDesc", //opt

"pmid": 4, //opt

"cutomerid": 4, //opt

"status": 1 //opt }

Response: { "projectid": 4 }