Integrator best practices
Learn how to build app that reliably interacts with the TextMaster API and provides the best experience for you users.
This guide will help you build an app that provides the best experience for your users and ensure that it's reliably interacting with the API.
A project holds metadata such as language pairs, category, general briefing, author assignment methods, templates, options, etc. It's a placeholder made of one or multiple documents. A document is the element corresponding to the expected content to be worked on. It's attached to a project and its characteristics are specific.
For translation and proofreading, the size of your documents will depends on the number of words of your content. When you are sending your content directly through our API as plain text, you should add documents to project in batch.
TextMaster's API will abort any connection which takes longer than 30 seconds to execute. Depending on the size of your content and the endpoint you use to create documents you might hit this limit. Using the batch API will ensure that the HTTP payload size stays reasonably small and requests succeed.
If you need to add a large number of documents to a project, you can split even further by making multiple batch requests. Using a "divide & conquer" strategy here will make sure you never hit the API limits.
For example, let's say you want to create a project with
100documents. Each document size depends on its individual content (number of words to translate) but average out around
100_000words. It would not be reasonable to expect the API to accept a single batch request made of
100documents with roughly
100_000 * 100words. You would simply hit the 30 seconds timeout limit and the connection would be aborted.
You should instead split into multiple batch requests of for example
10documents each or even lower. Use common sense here to make reasonably sized requests against the API.
Tips: You cannot add more than
99_999documents to a single project.
TextMaster currently accept your content as either plain text or a URL that points to a file either hosted on a remote location by yourself or through our upload API. Whenever possible, you should prefer sending your content as a file URL to prevent potential performance issues with large content.
When sending your content by using your hosted URL, TextMaster will create a copy of your file to be hosted on our platform.
You can either request your content or being it pushed to you using webhooks. Webhooks should always be preferred as you reduce the risk of hitting API limits when dealing with large documents.
It's also usually easier to implement a server for receiving events as they happen on TextMaster rather than randomly polling the API for status updates.
Hint: Always prefer using webhooks over HTTP polling for reliability.
It's very important that you secure the payloads sent from TextMaster. Although no personal information (like passwords) is ever transmitted in a payload, leaking any information is not good. Some information that might be sensitive include client email address or project content.
There are several steps you can take to secure receipt of payloads delivered by TextMaster:
- Ensure that your receiving server is on an HTTPS connection. By default, TextMaster will verify SSL certificates when delivering payloads. Any SSL errors will be logged in the webhook's response.
- You can add the IP address we use when delivering hooks to your server's allow list. Please note that we do make changes to our IP addresses from time to time. We do not recommend allowing by IP addresses, however if you use these we strongly encourage regular monitoring of our documentation. Our current public IP addresses are the following:
Warning: Our public IP addresses are subject to changes, we do not encourage using IP addresses to secure payload delivery.
- Provide a secret token to ensure payloads are definitely coming from TextMaster. By enforcing a secret token, you're ensuring that any data received by your server is absolutely coming from TextMaster. Ideally, you should provide a different secret token per user of your service. That way, if one token is compromised, no other user would be affected.
TextMaster expects that integrations respond within 30 seconds of receiving the webhook payload. If your service takes longer than that to complete, then TextMaster terminates the connection and the payload is lost.
Note that even with a background job running, TextMaster still expects your server to respond within 30 seconds. Your server needs to acknowledge that it received the payload by sending some sort of response. It's critical that your service performs any validations on a payload as soon as possible, so that you can accurately report whether your server will continue with the request or not.
Hint: Prefer handling webhooks asynchronously to avoid timeout issues.
You can list recent deliveries to quickly look whether a delivery was successful or failed.
You should make use of proper HTTP status codes in order to inform users. You can use codes like
202to acknowledge receipt of payload that won't be processed (for example, a payload delivered by a project with a stale status). Reserve the
500error code for catastrophic failures.
Hint: Use appropriate status code to communicate what happened.
Users can dig into the server responses you send back to TextMaster. Ensure that your messages are clear and informative.
Hint: Provide clear information in the webhook response body to communicate what happened.
TextMaster is explicit in telling you when a resource has moved by providing a redirect status code. You should follow these redirections. Every redirect response sets the
Locationheader with the new URI to go to. If you receive a redirect, it's best to update your code to follow the new URI, in case you're requesting a deprecated path that we might remove.
Often, API responses contain data in the form of URLs. For example, when requesting a document, we'll send a key called
author_workwith a URL you can use to retrieve your content.
For the stability of your app, you shouldn't try to parse this data or try to guess and construct the format of future URLs. Your app is liable to break if we decide to change the URL.
There are multiple webhook event types, and each event can have multiple actions. As TextMaster's feature set grows, we will occasionally add new event types or add new actions to existing event types. Ensure that your application explicitly checks the type and action of an event before doing any webhook processing. The
X-TextMaster-Eventrequest header can be used to know which event has been received so that processing can be handled appropriately.
Although your code would never introduce a bug, you may find that you've encountered successive errors when trying to access the API.
Rather than ignore repeated
5xxstatus codes, you should ensure that you're correctly interacting with the API. For example, if an endpoint requests a string and you're passing it a numeric value, you're going to receive a 4
xxvalidation error, and your call won't succeed. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a
Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse.