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.
Add documents to project in batch
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 100 documents. Each document size depends on its individual content (number of words to translate) but average out around 100_000 words. It would not be reasonable to expect the API to accept a single batch request made of 100 documents with roughly 100_000 * 100 words. 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 10 documents each or even lower. Use common sense here to make reasonably sized requests against the API.
Tips: You cannot add more than 99_999 documents to a single project.
Favor sending your content as files
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.
Favor webhooks to retrieve your content
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.
Secure payloads delivered from TextMaster
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.
Favor asynchronous work over synchronous
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.
Since it's impossible to predict how fast your service will complete, you should do all of "the real work" in a background job. Sidekiq (for Ruby), RQ (for Python), or RabbitMQ (for Java) are examples of libraries that can handle queuing and processing of background jobs.
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.
Use appropriate HTTP status codes
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 201 or 202 to acknowledge receipt of payload that won't be processed (for example, a payload delivered by a project with a stale status). Reserve the 500 error code for catastrophic failures.
Hint: Use appropriate status code to communicate what happened.
Provide as much information as possible to the user
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.
Follow any redirects that the API sends you
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 Location header 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.
Don't manually parse URLs
Often, API responses contain data in the form of URLs. For example, when requesting a document, we'll send a key called author_work with 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.
Check the event type and action before processing the event
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-Event request header can be used to know which event has been received so that processing can be handled appropriately.
Dealing with API errors
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 4xx and 5xx status 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 4xx validation error, and your call won't succeed. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a 4xx error.
Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse.
Last updated
