First Steps With Text United API
Technically, API stands for Application Programming Interface. In ‘Tech Jargon for Dummies’, if it existed, APIs would be described as sets of requirements that inform one application on how to talk to another. When you think about it, APIs are great time savers, offering user convenience in many cases. When you look at it more broadly, APIs are the little gems that make web-service mashups really possible. That’s why most large companies have built APIs for their customers, or for internal use.
If you thought that Text United is one of them, you were right! We have our own API and we believe it’s an incredibly efficient way to manage your translation project. If you want to start using it, we have great news for you! We want to officially welcome you to our new blog series for tech-savvy users that explain thoroughly how to use Text United API to Manage a Translation Project. We created this series for those, who want to familiarize themselves with our system and become advanced in handling translation projects through it step by step.
In the first part of the series, we will go slow and in three short steps explain what are the helper methods you should be familiar with and which method classes you should know before starting the project and tell you how to add the supported languages and company users to the project, which will be the introduction to part two of our series. Are you ready? Download the API Example Package, get ready and just keep on reading!
Disclaimer: The example code is a C# console application created in Visual Studio 2017 by our developers. You can read about the API method it uses here. The main code of the example is placed in the Main() method of the Program.cs. It includes all the steps needed to create a project, upload file(s), checks their statuses, generates translated versions and download translations.
Step #0.1: Get Familiar with Helper Methods of Text United API
What we would like to provide you with at the beginning is the basic knowledge that will help you dig deeper as we advance. Some repetitive operations performed in most of the steps are defined in a form of helper methods that are described below.
#1.WebRequest GetRequest(string uri, string httpMethod)
The helper method that accepts URI of the API method (with all the parameters, if needed) and the HTTP request method (i.e. GET, PUT, POST, DELETE). It returns a WebRequest object that may be used to get a response from the server. The request object includes credentials needed to authenticate and authorize the call. See authCompanyId and authApiKey constants defined in a Program class. They are used in the GetRequest() method to identify a caller. Get your Company ID and API Key from a Text United portal (after you login into a corporate account).
#2.WebRequest GetPostRequest (string uri, object modelToPost, out string jsonToPost)
A POST version of the GetRequest() method. It allows you to create a web request object with a JSON structure inside. The JSON string is built from the modelToPost parameter passed to the method. When calling an API’s POST method that requires passing an input data, simply create a model class representing the input data structure and pass it as the second parameter to the method.
For debugging purposes the method accepts additionally an output parameter jsonToPost. Use it to see the raw JSON string included by the method in the request object.
#3.string GetResponseJson(WebResponse response)
A method that extracts JSON data retrieved in a response from the server. Pass the WebResponse object as a parameter to the method. The result is a JSON string representing a result from the server. In order to facilitate processing of the data being sent back and forth between the application and the server, use model classes that represent data structures returned from the server or passed to the server in a form of the JSON strings.
Step #0.2: Get Familiar with Model Classes of Text United API
Using model classes makes it easier to convert JSON strings into objects and vice-versa. All the model classes used in the example are located in a Model folder of the project. Here is the complete list of them with descriptions:
– an item in a analysis result set. It represents statistics of words, characters and segments at the given matching range.
– an object that represents a source file that can be uploaded to the project. It includes the name of the file and its content.
– an object that represents a project to be created. Contains all the data needed to create a project, notably its name, source and target languages, a collection of source files and a translator ID.
– an object that represents a project in a list of all projects created by the company in Text United cloud. Properties of the most importance are: project ID, name, state and progress.
– a detailed information about the project including a collection of files, the project team (translators, proofreaders, etc.), analysis, as well as translation memories and terminology repositories linked to the project.
– an item in the list of files that belongs to a project. Among properties of the object are file ID, name, size and status of the file. The Status property informs you whether the file is waiting for processing (“Waiting”), had been processed successfully but no translated version of it was generated yet (“NotTranslated”), has been processed successfully and there’s a translated version of the file waiting for download (“Translated”). The state also indicates errors, such as source file processing failure (“ProcessingError”) or an error while generating a translated version of the file (“TranslationError”).
– an object that represents a downloaded file. It includes file’s name and the content.
– an object representing one of the languages supported by the system.
– an item in a list of project team members. Represents a system user that was assigned a role (e.g. translator or proofreader) in the project.
– an item in the list of the terminology repositories linked to the project.
– an item in the list of translation memories lined to the project.
Step #1. Get Supported Languages
There’s a block of code responsible for retrieving a list of all languages supported by the system. You will need at least two language objects later on to define a project’s source and target languages. The project creation method requires you to provide the respective language IDs. You may get to know that IDs by getting the list of all languages. Then you may select the appropriate ones.
To get the list:
1) register at Text United
2) go to https://www.textunited.com/api/languages
The result is a collection of JSON objects that can be then converted into ApiSystemLanguage objects.
Step #2. Get Company Users
This section displays a list of all company users registered in Text United. You will need at least one of those users to specify a translator for the project.
And we will explain how to create a project and proceed with it in Part Two of our series!