TruLinks

Best practices for integrators

Interested in integrating with the TruLinks platform? 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.

Secure payloads delivered from TruLinks

It's very important that you secure the payloads sent from TruLinks. Due to the nature of some of the APIs, personal information may be transmitted in a payload, leaking any information is not good. Some information that might be sensitive include email address or phone numbers. We will never transmit user Passwords in a payload.

There are three steps you can take to secure receipt of payloads delivered by TruLinks:

  1. Ensure that your receiving server is on an HTTPS connection. By default, TruLinks will verify SSL certificates when delivering payloads.

  2. Provide a secret token to ensure payloads are definitely coming from TruLinks. By enforcing a secret token, you're ensuring that any data received by your server is absolutely coming from TruLinks. 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

TruLinks expects that integrations respond within 10 seconds of receiving the webhook payload. If your service takes longer than that to complete, then TruLinks 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. Resque (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, TruLinks still expects your server to respond within thirty 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.

Dealing with rate limits

The TruLinks API rate limit ensures that the API is fast and available for everyone.

If you hit a rate limit, it's expected that you back off from making requests and try again later when you're permitted to do so. Failure to do so may result in the banning of your app.

You can always check your rate limit status at any time. Checking your rate limit incurs no cost against your rate limit.

Dealing with abuse rate limits

Abuse rate limits are another way we ensure the API's availability. To avoid hitting this limit, you should ensure your application follows the guidelines below.

  • Make authenticated requests, or use your application's client ID and secret. Unauthenticated requests are subject to more aggressive abuse rate limiting.

  • Make requests for a single user or client ID serially. Do not make requests for a single user or client ID concurrently.

  • If you're making a large number of POST, PATCH, PUT, or DELETE requests for a single user or client ID, wait at least one second between each request.

  • When you have been limited, use the Retry-After response header to slow down. The value of the Retry-After header will always be an integer, representing the number of seconds you should wait before making requests again. For example, Retry-After: 30 means you should wait 30 seconds before sending more requests.

  • Requests that create content which triggers notifications, such as issues, comments and pull requests, may be further limited and will not include a Retry-After header in the response. Please create this content at a reasonable pace to avoid further limiting.

We reserve the right to change these guidelines as needed to ensure availability.

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 5xx validation error, and your call won't succeed. Similarly, attempting to access an unauthorized or non-existent endpoint will result in a 4xx error.

Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse.