HomeGuidesRecipesAPI Reference

# Best Practices

Alation recommends that when making Create, Read, Update, or Delete API calls to Alation that:

  • Payload contains 1000 objects or less per call

  • Do not recommend multi-threading or multi-processing API calls to Alation

# Configure API Throttling

It is possible to rate-limit requests made by users to some of the Alation's public APIs. As of 2020.3, the API which can be throttled are:

  • [Lineage](🔗)

  • [BI Source (GBMv2) Overview](🔗)

  • [Relational Integration API Overview](🔗)

  • [Search](🔗)

API throttling **is disabled** by default. It can be enabled and configured from the Alation shell using the `alation_conf` command. To view all currently available configuration options for API throttling:

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

    
  2. Type the following command and press **Enter**:
    
This command prints all parameters relevant to API throttling and their current values:
NameDefaultDescriptionColumn Title
`alation.api.throttling.enabled`FalseEnables the throttling feature. No restart required.
`alation.api.throttling.global.read`nullSets the global API rate limit for READ request types. Global settings apply to those APIs which respect throttling, not all available Alation APIs. [null]{.title-ref} means _unlimited_.
`alation.api.throttling.global.write`nullSets the global API rate limit for WRITE request types. Global settings apply to those APIs which respect throttling, not all available Alation APIs. [null]{.title-ref} means _unlimited_.
`alation.api.throttling.lineage.read`20/secSets the rate limit for READ request types specifically for the Lineage V2 API.
`alation.api.throttling.lineage.write`20/secSets the rate limit for WRITE request types specifically for the Lineage V2 API
`alation.api.throttling.bi.read`20/secSets the rate limit for READ request types specifically for the GBM V2 API.
`alation.api.throttling.bi.write`20/secSets the rate limit for WRITE request types specifically for the GBM V2 API.
`alation.api.throttling.rdbms_integration_apis.read`20/secSets the rate limit for READ request types specifically for the relational integration API.
`alation.api.throttling.rdbms_integration_apis.write`20/secSets the rate limit for WRITE request types specifically for the relational integration API.
`alation.api.throttling.search.read`20/secSets the rate limit for READ request types specifically for the search API.
# Enable API Throttling
To enable API Throttling for an Alation instance, set the parameter `alation.api.throttling.enabled` to `True`. No restart is required:

After enabling the feature, set the throttling scope parameters to appropriate 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/ API resource 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.
  • Set using the parameters:
    • `alation.api.throttling.lineage.read`
    • `alation.api.throttling.lineage.write`
    • `alation.api.throttling.bi.read`
    • `alation.api.throttling.bi.write`
Each scope type comes with two variations:
  • **READ**: applies to GET, OPTIONS. For example:
`alation.api.throttling.lineage.read = 20/sec`
  • **WRITE**: applies to POST, PATCH, DELETE. For example:
`alation.api.throttling.lineage.write = 20/sec`
**Note**
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:

# 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**

**Example 2**