The GPI Translation Services API – Part 2

May 11, 2016 Mohamed Gamal

The Globalization Partners International (GPI) Translation API is a technology agnostic platform which enables companies to access GPI's translation services provided by our global team of professional, native-speaking translators.

Part one of the GPI Translation Services API series, I briefly explained how it works. In part two of this series, I will give an in-depth guide to using the API.

Getting Started with the GPI Translation API

The GPI Translation API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication.

The following describes the high-level process for authentication:

  1. Developer concatenates selected elements of the request to form a string.
  2. Using your GPI-SECRET-KEY, the developer calculates the HMAC of that string.
  3. Developer includes the computed HMAC signature as a parameter of the request by using the Request Signing syntax described below.
  4. GPI receives your request, we fetch the GPI-API-KEY that you claim to have and use it in the same way to compute a signature for the message it received.
  5. If the signature we compute matches the signature in your request, we conclude that the requester has access to the GPI-SECRET-KEY and the request is authenticated.
  6. If the two signatures do not match, the request is dropped and the system responds with an error message.

How it Works

The GPI Translation API uses both the standard HTTP Authorization header and a custom header to pass authentication information.

The headers have the following form:

Authorization: GPI-HMAC Signature

X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

Developers are issued a GPI-API-KEY and GPI-SECRET-KEY when they register. For request authentication, the GPI-API-KEY identifies the developer making the request.

The Signature is the HMAC-SHA256 encoded representation of selected elements from the request, and will vary from request to request.

If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the GPI-SECRET-KEY.

The request will then be processed under the context of the developer to whom the key was issued.

Request Signing

The following illustrates the construction of the Authorization request header:

 

Authorization = "GPI-HMAC" + " " + Signature;
           
Signature = Base64( HMAC-SHA256( Your-GPI-SECRET-KEY, UTF-8-Encoding-Of( StringToSign ) ) );
           
StringToSign = HTTP-Verb + "\n" +
    Content-MD5 + "\n" +
    Content-Type + "\n" +
    Date + "\n" +
    CanonicalizedHeaders +
    CanonicalizedResource;
           
CanonicalizedResource = [ "/" + <resource-endpoint-absolute-path> ];
CanonicalizedGpiHeaders = <described below>

 

NOTE: In the example above, "\n" means the Unicode code point U+000A, (i.e. called newline character).

 

HMAC-SHA256 is a hashing algorithm that takes two byte-strings, a key and a message as input

For the GPI Translation API request authentication, use your GPI-SECRET-KEY as the key, and the UTF-8 encoding of the StringToSign as the message.

The output of HMAC-SHA256 is also a byte string, called the digest.

Finally, the Signature request parameter is constructed by Base64 encoding this digest.

Canonicalized GPI Headers

To construct the CanonicalizedGpiHeaders part of StringToSign, select all HTTP request headers that start with 'X-GPI-' (using a case-insensitive comparison), and use the following process:

  1. Lowercase each HTTP header name. For example, 'X-GPI-KEY' becomes 'x-gpi-key'.
  2. Sort the collection of headers in lexicographical order by header name.
  3. Merge liked-named header fields into a single entry '<header-name>:<comma-separated-value-list>', without any whitespace between values.
  4. Convert multi-line headers into a single line by replacing the whitespaces (including new-line) with a single space.
  5. Trim any whitespace around the colon in the header. For example, the header 'x-gpi-key: 12345' would become'x-gpi-key:12345'.
  6. Append a newline character (U+000A) to each canonicalized header, concatenating all headers into a single string.

Positional vs. Named HTTP Headers

The first few header elements of StringToSign (Content-TypeDate, and Content-MD5) are positional. The header names are not included in StringToSign but only their values from the request.

In contrast, the 'x-gpi-' elements are named. Both the header names and the header values must appear in StringToSign.

If a positional header required by StringToSign is not present in your request, use an empty string ("") for that position.

Specifying the Date Header

All authenticated requests must include the Coordinated Universal Time (UTC) timestamp for the request. You can specify the timestamp either in the x-gpi-date header, or in the standard HTTP/HTTPS Date header.

If both headers are specified on the request, the value of x-gpi-date is used as the request's time of creation.

NOTE: Some HTTP client libraries do not expose the ability to set the Date header for a request.

In cases like these, you can set the timestamp for the request by using an x-gpi-date header instead. Therefore, if you include the x-gpi-date header, use the empty string for the Date when constructing the StringToSign.

Examples

For the following examples, we will use the (non-working) keys in the following table.

Key                                        Value

GPI-API-KEY                            C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

GPI-SECRET-KEY                     s!kNYGY,PO4rUvj=o%:h3p/VpaP+!coQ+pJfPsbg2]m.=akLjC%=uqurW%f&~<gE

Example 1

Request - GET Quote #2510

 

 GET /quotes/2510 HTTP/1.1                                                      
 Host: api.globalizationpartners.com
Date: Tue, 29 Jul 2014 10:00:00 +0000
           
Authorization: GPI-HMAC NTA1MTNkYzk3ZWQ3ZWVhOWZmZDM3YTcyZmJmZjZiYWQ4Yjg2Mzk3ZTE2OGIwNmRmNzA3MDY4MTlmZDc0Nzk1Yw==
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

 

StringToSign

 

 GET\n
\n
\n
Tue, 29 Jul 2014 10:00:00 +0000\n
x-gpi-api-key:C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8\n
/quotes/2510

Example 2

 

Request - DELETE Quote #2510

 

 DELETE /quotes/2510 HTTP/1.1                                                      
 Host: api.globalizationpartners.com
Date: Tue, 29 Jul 2014 10:00:00 +0000
           
Authorization: GPI-HMAC NGI0ZjJiNDZjMWJiMDQxM2M0ZmY5ZmEyNzgxMjk4MGU3YjgxNmJlN2Q0YzMzMjljMTkzNjdiN2NiY2Y5NWNmOA==
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8

 

StringToSign

 

 DELETE\n
\n
\n
Tue, 29 Jul 2014 10:00:00 +0000\n
x-gpi-api-key:C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8\n
/quotes/2510

Example 3

 

Request - GET Quote #2510 using X-GPI-DATE

 

 GET /quotes/2510 HTTP/1.1                                                       
 Host: api.globalizationpartners.com
Date: Tue, 29 Jul 2014 10:00:00 +0000
           
Authorization: GPI-HMAC Y2M1MjUxNzEwYzc0ZjkzNjYzNTFkOWZhNTM4YmZlOWQ3ZDAwNDYxODEwNjZiMWFhNzMxNGZhMmU0YjgyMGEzNg==
X-GPI-API-KEY: C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8
X-GPI-Date: Tue, 29 Jul 2014 10:00:00 +0000

 

StringToSign

 

 GET\n
\n
\n
\n
x-gpi-api-key:C5A38965F6CD88C43D05D43A5955D7242B1241924666EB04A966C4061C15FED8\n
x-gpi-date:Tue, 29 Jul 2014 10:00:00 +0000\n
/quotes/2510

 

Notice how the 'X-GPI-' headers are sorted, trimmed of whitespace, and converted to lowercase.

NOTE: Multiple headers with the same name have been joined using commas to separate values.

Request Signing Problems

When request authentication fails, the GPI Translation API will responds to the request with a JSON error object.

This information is meant to help developers diagnose the signing issue.

Further GPI Resources on Connectors and Website Development

GPI offers custom  WCMS Translation Connectors to a variety of web content management systems in order to streamline localization workflows and access to translation project information across your enterprise. Connectors and Plugins include:

You may also find some of the following articles and links useful:

Further Information on Localization Resources

GPI frequently assists customers with multilingual website design, development and deployment, and has developed a suite of globalization tools to help you achieve your multilingual website localization project goals. You can explore them under the  Translation tools and Portals section of our website.

Please feel free to contact GPI at info@globalizationpartners.com with any questions about our language and technology services. Also let us know if you have any interesting blog topics you would like us to cover in our future blogs. You may request a complimentary Translation Quote for your projects as well.

 

About the Author

Mohamed Gamal

Globalization Application Developer. Mohamed is a native Arabic speaker from Giza, Egypt. He has over 5 years’ experience in software and websites development projects. His experience includes working with multiple web frameworks, and approaches to web development using a range of tools and technologies including C#, ASP.Net MVC, LINQ, PHP, Django, HTML5/CSS3, JS, NodeJS, AngularJS, JQuery, MqSql PostgreSQL, SQL Server & VoIP with O.S.: Linux, Windows, OSX. He has experience in GIS and data collection projects working as a GEO-Spatial Application Developer. Mohamed has worked with various companies including CartoLogic, a leading 3D and spatial software consultancy and Tawasol, a mobile apps & portals, Websites & web-based apps, Digital strategy & e-marketing solutions company in Egypt. He worked as an application developer on a range of software development teams of varying sizes delivering solutions for both public and private sector clientele.

More Content by Mohamed Gamal
Previous Article
Iran: Farsi Translation and Localization
Iran: Farsi Translation and Localization

Iran, known as Persia until 1935, is located in West Asia and borders the Caspian Sea, Persian Gulf and Gul...

Next Article
The Rise of Ecommerce in the MENA Region
The Rise of Ecommerce in the MENA Region

The MENA region's ecommerce market will continue to grow in 2016. The market for physical products sold onl...

Ready to translate your documents, software or website?

Request a Quote!