Best Practices

When you make Create, Read, Update, or Delete API calls to Alation, we recommend that:

• Payloads contain 1000 objects or less per call
• You do not use multi-threading or multi-processing API calls

It is possible to rate-limit requests made by users to some of Alation's public APIs. The APIs that can be throttled are:

• BI Source (GBMv2) API
• Data Dictionary API
• Documents API
• Folders API
• Lineage API
• Relational Integration API
• SCIM API
• Search API

Throttling is disabled by default. Instructions for enabling and configuring throttling can be found below.

Enable API Throttling

To enable API Throttling for an Alation instance, set the alation_conf parameter alation.api.throttling.enabled to True. No restart is required.

{.Bash}

alation_conf alation.api.throttling.enabled -s True

For help with alation_conf, see Using alation_conf.

📘

Server Configuration for Alation Cloud Service

Alation Cloud Service customers can request server configuration changes through Alation Support.

After enabling the feature, configure the throttling scope parameters as explained below.

Configure API Throttling

To view all currently available configuration options for API throttling:

1. On the Alation host, enter the Alation shell:

   {.Bash}

   sudo /etc/init.d/alation shell
   

2. Type the following command and press Enter:

   {.Bash}

   alation_conf throttling
   

This command prints all parameters relevant to API throttling and their current values:

Set Throttling Scope Parameters

There are two major throttle scope types:

Global (Sustained)

• Applies to all APIs which respect throttling.
• It is recommended to set the rate limit to a larger value. For example: 1,000 requests per day.
• Set using the parameters:
  • alation.api.throttling.global.read
  • alation.api.throttling.global.write

API Family-Specific

• Applies to the particular API scope only (for example, Lineage V2 or GBM V2).
• It is recommended to set the rate limit to a small duration to limit expensive operations or throttle DOS attacks. For example, 20 requests per second.

Each scope type comes with two variations:

• READ: applies to GET requests. For example:
  alation.api.throttling.lineage.read = 20/sec
• WRITE: applies to POST, PUT, PATCH, and DELETE requests. For example:
  alation.api.throttling.lineage.write = 20/sec

📘

Precedence

Throttle configurations are applied based on scope and request type. The API family scope takes precedence over the Global settings when both are set.

Value Format

Rate limit can be set in the following format:

• Number of requests per second: <number>/sec.
  • Example: 20/sec
• Number of requests per minute: <number>/min.
  • Example: 20/min
• Number of requests per hour: <number>/hour.
  • Example: 20/hour
• Number of requests per day: <number>/day.
  • Example: 20/day
• null: means unlimited, or throttling disabled. You can disable each rate limit by setting it to null. The global rate limit is disabled by default.

To set a value, use the alation_conf command:

 alation_conf alation.api.throttling.lineage.read -s <value>

📘

Server Configuration for Alation Cloud Service

Alation Cloud Service customers can request server configuration changes through Alation Support.

Throttle Response

If a rate limit for a scope is set to <number>/<time unit>, then an API request within this scope is throttled on <number> + 1 attempt after the time = <time unit>. When a request is throttled, the API responds with status 429 and the time in seconds till the next request in this scope is allowed.

Example 1

 [
   {
     "code": "429000",
     "detail": "Rate limit for [read] requests for API scope [lineage] reached. Expected available in 29 seconds."
     }
   ]

Example 2

 [
   {
     "code": "429000",
     "detail": "Global rate limit for [read] requests reached. Expected available in 86279 seconds."
     }
   ]