Applanga API


Version: 1.0.3

URL: https://applanga.com


Requirements & Usage

  1. To make requests to the Applanga API you first need to create an App in the Applanga Dashboard.

  2. Then you need to request an API Access Token. Go to the App Settings (click App Settings in the App overview), and click Show API Token. For this to work however you need to contact Applanga via mail at info@applanga.com to enable API access for your App.

Authorization

  1. With your API Token you can now query the API at https://api.applanga.com/v1/api?app={app_id}. To authenticate your request you need to set the Authorization header to carry your API Token in the bearer format (as described here https://tools.ietf.org/html/rfc6750#page-5 ). The value of the Authorization header needs to be 'Bearer {apiToken}'. Example: Authorization: Bearer xxxxxxxxxxxxxxxxxxxx!xxxxxxxxxxxxxxxxxxxxxx

  2. You also need to pass the id of your app to the query with the app parameter. https://api.applanga.com/v1/api?app={app_id}. The app_id is the first part of your API token until the ! e.g. if your API Token would be 54e49f570de187711f9a5936!64d6e85c0111f758748898e3181a25b7 the app_id is 54e49f570de187711f9a5936.

  3. For API write access, as an additional security measure you have to specify a list of authorized IP's or IP ranges. Go to your app in the Applanga Dashboard, click App Settings, if you have API access you will have an input field below Show API Token which will allow you to enter IP addresses (ipv4 and ipv6) or address ranges in CIDR Notation (https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). To allow write access from all ipv4 addresses add 0.0.0.0/0, for all ipv6 addresses ::/0. For unrestricted access add both. Not adding any IP addresses/ranges will block all write access.

Requesting translation data

  1. Send a GET request to https://api.applanga.com/v1/api?app={app_id}. The API will identify your App and authenticate the token and return your App translation data. The response will be a json with the following structure:

     {
         "_id":"yourAppId",
         "__v":"1.0",
         "draftModeEnabled":true,
         "collectMissingEnabled":false,
         "baseLanguage":"en",
         "name":"yourAppName",
         "data":{
             "en":{
                 "main":{
                     "version":"25",
                     "entries":{
                         "MenuTitle1 key":{
                             "d":"Menu Title1 draft",
                             "v":"Menu Title1 value",
                             [optional] "src":"/en/menu_strings.xml"
                         },
                         "MenuTitle2 key":{
                             "d":"Menu Title2 draft",
                             "v":"Menu Title2 value",
                             [optional] "src":"/en/menu_strings.xml"
                         },
                         ...
                     },
                     ...
                 },
                 ...
             }
         }
     }
    

    For typical apps without configured groups the response will only contain one group named "main".

  2. The API is using a Content Delivery Network for fast and reliable content distribution. It is updated in fixed intervals and it therefore might take up to 10 minutes until changes made in the dashboard appear live in the api.

  3. To limit the response data to certain groups, and/or languages you can add query parameters requestedLanguages and requestedGroups, as json string arrays which have to be urlencoded as well. An Example for requested group main and languages en and de : https://api.applanga.com/v1/api?app={app_id}&requestedGroups=[%22main%22]&requestedLanguages=[%22en%22,%22de%22].

  4. If you do not request any languages or groups, all groups and languages will be returned. If you have not activated groups and created additional groups, all your translations will be in group main.

  5. Translations can have a src property which describes a file origin for the specific string in that specific language. These file sources can originate from imported .xliff files or from data writte through this API. By default this property is excluded from the response data. To include it add a query param includeSrc with the value true. Example: https://api.applanga.com/v1/api?app={app_id}?includeSrc=true

Posting translation data

  1. Send a POST request to https://api.applanga.com/v1/api?app={app_id} with a json body matching the JSON Schema (http://json-schema.org/) described under JSON Schema for API write access. The API will identify your App and authenticate the token. If your request is authorized the data will be written to your app and a json object describing the changes will be returned. Otherwise you will receive an http error. Don't forget to set the Content-Type: application/json header.

  2. You can also add a set of options to your request body to specify how the write operation should be performed. The following options can be set as members of an options property in the request body:

    2.1. onlyAsDraft: take draft or value from input and store in draft. default: false

    2.2. onlyIfTextEmpty: only write draft or value if its empty. default: false

    2.3. skipLockedTranslations: don't change locked translations. default: false 2.4. setStatus: set status of all submitted transations to possible values: 0 (remove status); 1 (accepted); 2 (needs review); 3 (needs translation); 4 (rejected). default: no status change

  3. Example JSON body for four translations in language en, group main, status set to accepted and only drafts being written:

     {
         "options":{
             "onlyAsDraft":true,
             "setStatus":1
         },
         "data":{
             "en":{
                 "main":{
                     "entries":{
                         "key1":{
                             "d":"draft1",
                             "v":"value1",
                             "src":"/src/File1"
                         },
                         "key2":{
                             "d":"draft2",
                             "v":"value2",
                             "src":"/src/File2"
                         },
                         "key3":{
                             "d":"draft3",
                             "v":"value3",
                             "src":"/src/File3"
                         },
                         "key4":{
                             "d":"draft4",
                             "v":"value4",
                             "src":"/src/File45"
                         }
                     }
                 }
             }
         }
     }
    

JSON Schema for API write access

This describes the format of the json body expected for an API POST request Also see http://json-schema.org/.

Note: The format returned by a GET request also matches this format, with the addition of a version field to the group data object.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Api - Translation data input format",
    "description": "A data object describing translation entries ordered by groups and languages",
    "type": "object",
    "additionalProperties": false,
    "required": ["data"],
    "properties": {
        "options": {
            "description": "options describing how to handle the input",
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "onlyAsDraft": {
                    "description": "take draft or value from input and store in draft",
                    "type": "boolean",
                    "default": "false"
                },
                "onlyIfTextEmpty": {
                    "description": "only write draft or value if its empty",
                    "type": "boolean",
                    "default": "false"
                },
                "skipLockedTranslations": {
                    "description": "don\"t change locked translations",
                    "type": "boolean",
                    "default": "false"
                },
                "setStatus": {
                    "description": "0->nostatus; 1->accepted; 2->needs review; 3->needs translation; 4->rejected",
                    "oneOf": [
                    {
                      "type": "string",
                      "enum": ["0", "1", "2", "3", "4"]
                    },
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 4
                    }
                  ]
                }
            }
        },
        "data":{
            "description": "top level data object",
            "type": "object",
            "additionalProperties": false,
            "minProperties": 1,
            "patternProperties": {
                "^[a-zA-Z\-]*$":{
                    "description": "dataset mapped to a language name",
                    "type": "object",
                    "additionalProperties":false,
                    "minProperties": 1,
                    "patternProperties": {
                        ".*":{
                            "description": "dataset mapped to a group name",
                            "type": "object",
                            "additionalProperties":false,
                            "properties":{
                                "entries": {
                                    "description": "translation data map",
                                    "type": "object",
                                    "additionalProperties":false,
                                    "minProperties": 1,
                                    "patternProperties": {
                                        ".*":{
                                            "description": "the actual language entry data",
                                            "type": "object",
                                            "properties":{
                                                "d" : {
                                                    "type": "string"
                                                },
                                                "v" : {
                                                    "type": "string"
                                                },
                                                "src" : {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Requesting screenshots

Send a GET request to https://api.applanga.com/v1/api/screenshots?app={app_id}. The API will identify your App and authenticate the token and return all the screenshots of the App. The response will be a json with the following structure:

[
    {
        "url": "https://s3.eu-central-1.amazonaws.com/applanga/......jpg",
        "originalName": "CyOrcrgVIAAJLDt.jpg_Test1",
        "mimetype": "image/jpeg",
        "tag": {
            "name": "Test1",
            "created": "2017-11-28T14:16:59.083Z",
            "updatedAt": "2017-11-28T15:12:29.651Z",
            "languageEntryIds": [
                "Test1"
            ]
        },
        "metadata": {
            "width": 480,
            "height": 635,
            "deviceModel": "IPhone",
            "operatingSystem": "iOS",
            "bundleVersion": "1.0",
            "deviceLanguageLong": "English",
            "updatedAt": "2017-11-28T14:17:32.241Z",
            "stringPositions": [
                {
                    "key": "Test1",
                    "x": 100,
                    "y": 10,
                    "width": 200,
                    "height": 40
                }
            ]
        }
    },
    ...
]