TDL Integration | Toppan Digital language

Getting started

Authentication

API Usage

.Net - C# Authentication example

HTTP Authentication example

CUrl Authentication example

Javascript XHR Authentication example

Authentication

Our RESTful API implements the OAuth 2.0 grant type using Client Credentials. This grant type flow relies on the following steps:

You authenticate with our authorisation server and request an access token from our token endpoint.
Upon validation of your credentials, our authorisation server will issue an access token.
This access token will have to be included as an Authorization HTTP header on all of your subsequent requests to our API.

The token endpoint for the sandbox services is:

https://apitest.toppandigital.com/oauth2/token

The token endpoint for the live services is:

https://api.toppandigital.com/oauth2/token

A typical access token will be similar to the example shown below:

{
       "access_token": "{{ Bearer1 }}...{{ Bearer2 }}"
       "token_type": "bearer"
       "expires_in": {{ Expires_in }}
}

EXAMPLE ONLY

After successful authentication from our authorisation server you will need to add the access token to an Authorization HTTP header for all your subsequent API requests

The Authorization HTTP header's value will be prefixed with Bearer followed by a space and the access token you have obtained:

Authorization: Bearer {{ Bearer1 }}...{{ Bearer2 }}

EXAMPLE ONLY

.Net - C# Authentication example

Obtain a OAuth2 token with a request to STREAM's RESTful API authentication services.

The example assumes you have obtained your clientId and clientSecret and that you have replaced them accordingly on the code below.

To test the connection to the STREAM's RESTful API, let's call the authentication endpoint on our test server.

The following examples use Microsoft .NET Framework 4.7.2 and the C# language.
However, the code logic and the use of the API services extend to other languages and technologies.


                                using (HttpClient client = new HttpClient())

                                {

                                
                                    ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

                                    client.DefaultRequestHeaders.TryAddWithoutValidation("Content-Type", "application/x-www-form-urlencoded");

                                    

                                    HttpRequestMessage request = new HttpRequestMessage

                                    {

                                    

                                        Method = System.Net.Http.HttpMethod.Post,

                                        RequestUri = new Uri("https://apitest.toppandigital.com/oauth2/token"),

                                        Content = new System.Net.Http.FormUrlEncodedContent(new[] {

                                        
                                            new KeyValuePair<string, string>("grant_type", "client_credentials"),

                                            new KeyValuePair<string, string>("client_id", "9237f94025c64190a8459a802bc6df5e"),

                                            new KeyValuePair<string, string>("client_secret", "736b5527cc96da80cd7cca0942d59bffd53e99f89020fd3baf60e24d83b70a8bb")

                                        
                                        })

                                    
                                    };

                                    

                                    HttpResponseMessage response = client.SendAsync(request).Result;

                                    var sResp = response.Content.ReadAsStringAsync().Result;

                                    Console.WriteLine(sResp);



                                

                                }

If you are successful, you will receive a token to the one presented on the Authentication section (A typical access token):

HTTP Authentication example


                                POST /oauth2/token HTTP/1.1

                                Host: apitest.toppandigital.com

                                Accept: application/json

                                Content-Type: application/x-www-form-urlencoded

                                Content-Length: 151

                                

                                client_id=9237f94025c64190a8459a802bc6df5e&client_secret=736b5527cc96da80cd7cca0942d59bffd53e99f89020fd3baf60e24d83b70a8b&grant_type=client_credentials

CUrl Authentication example


                                curl --location --request POST 'https://apitest.toppandigital.com/oauth2/token' \

                                --header 'Accept: application/json' \

                                --header 'Content-Type: application/x-www-form-urlencoded' \

                                --data-urlencode 'client_id=9237f94025c64190a8459a802bc6df5e' \

                                --data-urlencode 'client_secret=736b5527cc96da80cd7cca0942d59bffd53e99f89020fd3baf60e24d83b70a8b' \

                                --data-urlencode 'grant_type=client_credentials'

Javascript XHR Authentication example


                                var data = "client_id=9237f94025c64190a8459a802bc6df5e&client_secret=736b5527cc96da80cd7cca0942d59bffd53e99f89020fd3baf60e24d83b70a8b&grant_type=client_credentials";

                                

                                var xhr = new XMLHttpRequest();

                                xhr.withCredentials = true;

                                

                                xhr.addEventListener("readystatechange", function() {

                                
                                    if
                                    (this.readyState === 4) {

                                    console.log(this.responseText);
                                    }

                                
                                });

                                

                                xhr.open("POST", "https://apitest.toppandigital.com/oauth2/token");

                                xhr.setRequestHeader("Accept", "application/json");

                                xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

                                

                                xhr.send(data);

Hello world

Create a proxy client that will allow you to comunicate to the STREAM API Web Services. If you use Microsoft .NET or Java development technologies, your IDE should allow you to quickly create a proxy client just by specifying the address of the WSDL, automatically generating the service reference and the necessary classes.

The following examples use Microsoft .NET Framework 3.5 and the C# language. However, the code logic and the use of the API services extend to other languages and technologies.

The examples assume that you were able to create a service reference to the STREAM API Web Services.

To test the connection to the STREAM API, let's call the HelloWorld service. This service exists only for connection testing purposes.

...
try
{
    //call the HelloWorld method
    string resultMessage = YourServiceReference.HelloWorld();

    //display the result message in the Output window
    System.Diagnostics.Debug.WriteLine(resultMessage);
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

If you are successful, you will receive the following message: "Hello World - You are connected to Toppan Digital Language." If your code is correct and you obtain an error while trying to connect, please make sure your internet connection is working.

Consuming some simple services

Some of the services that the STREAM API provides do not need authentication. For example, the GetLanguagesList method allows you to obtain a list of all the supported languages. Let's try to call this method.

...
try
{
    //call the GetLanguagesList method. This method returns an array of SOAPLanguage objects, which
    //represents a language in the STREAM system
    SOAPlanguage[] langs = YourServiceReference.GetLanguagesList();

    //display the obtained languages in the Output window
    foreach (SOAPlanguage lang in langs)
        System.Diagnostics.Debug.WriteLine(lang.languageID + " - " + lang.description);
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

If you are successful, you will obtain a list of languages. You can learn more about the GetLanguagesList method in our documentation page.

Consuming services that require authentication

Some services require you to authenticate yourself. To test the authentication let's call the HelloWorldWithAuthentication method. This method exists only for testing purposes.

To provide a secure use of our API, we use a Token based authentication. You will need to authenticate yourself using your account username and API Key. Upon a sucessful authentication, the API will generate and return an Authentication Token that you will use to make all posterior service calls. This Authentication Token has an activity expiration time, in a similar way to a session token.

...
//set up a Authentication Header with you authentication credentials
AuthenticationHeader credentials = new AuthenticationHeader();
credentials.Username = "YourUsername";
credentials.ApiKey = "YourPrivateApiKey";

try
{
    //authenticate and obtain the Authentication Token
    AuthenticationToken AuthToken = YourServiceReference.Authenticate(credentials);

    if (AuthToken.authenticationSuccessful)
    {
        //call the HelloWorlWithAuthentication method, passing the Authentication Token
        string resultMessage = YourServiceReference.HelloWorldWithAuthentication(AuthToken);

        //display the result message in the Output window
        System.Diagnostics.Debug.WriteLine(resultMessage);
    }
    else
    {
        //if the authentication is not successful, display the returned error message in the Output window
        System.Diagnostics.Debug.WriteLine(AuthToken.m_errors.description);
    }
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
    }
...

To authenticate and obtain an Authentication Token, you must call the Authenticate method, providing your authentication credentials. If the authentication fails, you will receive an error description message that will allow you to know why the authentication failed. You can learn more about the Authenticate method and possible error messages in the Documentation page.

If your call to the HelloWorldWithAuthentication method is successful, you will receive the message: "Hello World - You are authenticated and connected to Toppan Digital Language.".

Obtaining a quote for a translation

The STREAM API contains several functions to obtain a quote for the translation service, based on input parameters like: source and target languages, speciality, plain text or several other formats of source document, authenticity certification and some others advanced user settings.

Let's use the GetQuoteForPlainText to obtain a quote for a text translation.

...
try
{
    //get the language ID for the source language
    int languageSourceID = ((SOAPlanguage)YourServiceReference.GetLanguageID("English")).languageID;
    int specialityID = 16; // General (consult the specialities code list)

    //to keep the example simple, we are not checking if this is a available target language considering
    //the source language and the speciality
    int[] languageTargetID = { ((SOAPlanguage)YourServiceReference.GetLanguageID("French")).languageID };

    //the plain text to translate
    string plainText = "The quick brown fox jumps over the lazy dog";

    //call the GetQuoteForPlainText method. This method returns a SOAPreponse object
    SOAPresponse response = (SOAPresponse)YourServiceReference.GetQuoteForPlainText(AuthToken,
    languageSourceID, specialityID, languageTargetID, plainText);

    //check if there was an error during the quote calculation process
    if (response.m_errors.errorPresent == true)
    {
        System.Diagnostics.Debug.WriteLine(response.m_errors.errorCode + response.m_errors.description);
    }
    else
    {
        //display the quotes in the Output window
        foreach (SOAPquote quote in response.m_quotes)
        {
            System.Diagnostics.Debug.WriteLine("Quote ID: " + quote.idQuote +
            "Quote price: " + quote.dQuotePrice + quote.sCurrency +
            " Estimate: " + quote.dtTargetCompletion + " type? "
            + quote.byType + " Execution type(min): "
            + quote.iMinutesElapsed);
        }
    }
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

If you are successful you will obtains the quotes for the translation of the text. You can learn more about the GetQuoteForPlainText method in our Documentation page.

What's next?

After reading and trying our Quick Start, check our Documentation page to learn more about the STREAM API and each of our methods. You can also check our Examples page for pratical examples of how to use some of the API methods. If you need any additional help, please contact us.