mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
Docs: update API Limit related API reference docs
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7126 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: 1f50ee674493856385f3686ad3c675daffcf41ad
This commit is contained in:
Manas Agarwal
hasura-bot
parent
66b24014a6
commit
905e5439c9
112
docs/docs/api-reference/metadata-api/api-limits.mdx
Normal file
112
docs/docs/api-reference/metadata-api/api-limits.mdx
Normal file
@ -0,0 +1,112 @@
|
|||||||
|
---
|
||||||
|
sidebar_label: API Limits
|
||||||
|
sidebar_position: 20
|
||||||
|
description: Manage API limits configuration with the Hasura metadata API
|
||||||
|
keywords:
|
||||||
|
- hasura
|
||||||
|
- docs
|
||||||
|
- metadata API
|
||||||
|
- API reference
|
||||||
|
- security options
|
||||||
|
- API limits
|
||||||
|
- Rate limits
|
||||||
|
- limits
|
||||||
|
- enterprise
|
||||||
|
- ee
|
||||||
|
---
|
||||||
|
|
||||||
|
# Metadata API Reference: API Limits
|
||||||
|
|
||||||
|
<div className='badge badge--primary heading-badge'>Available on: Cloud, Enterprise Edition</div>
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
Here's the API to manage [API Limits](/security/api-limits.mdx) related metadata.
|
||||||
|
|
||||||
|
## set_api_limits {#metadata-set-api-limits}
|
||||||
|
|
||||||
|
You can configure api limits using the `set_api_limits` API.
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /v1/metadata HTTP/1.1
|
||||||
|
Content-Type: application/json
|
||||||
|
X-Hasura-Role: admin
|
||||||
|
|
||||||
|
{
|
||||||
|
"type": "set_api_limits",
|
||||||
|
"args": {
|
||||||
|
"disabled": false,
|
||||||
|
"depth_limit": {
|
||||||
|
"global": 5,
|
||||||
|
"per_role": {
|
||||||
|
"myrole": 3
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"node_limit": {
|
||||||
|
"global": 5,
|
||||||
|
"per_role": {
|
||||||
|
"myrole": 3
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"time_limit": {
|
||||||
|
"global": 5,
|
||||||
|
"per_role": {
|
||||||
|
"myrole": 3
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"batch_limit": {
|
||||||
|
"global": 5,
|
||||||
|
"per_role": {
|
||||||
|
"myrole": 3
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"rate_limit": {
|
||||||
|
"global": {
|
||||||
|
"unique_params": "IP",
|
||||||
|
"max_reqs_per_min": 100
|
||||||
|
},
|
||||||
|
"per_role": {
|
||||||
|
"myrole": {
|
||||||
|
"unique_params": ["x-hasura-id", "x-hasura-team-id"],
|
||||||
|
"max_reqs_per_min": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Args syntax {#set-api-limits-syntax}
|
||||||
|
|
||||||
|
| Key | Required | Schema | Description |
|
||||||
|
|-------------|----------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
|
||||||
|
| disabled | false | boolean | Default value is false (Limits are enabled by default) |
|
||||||
|
| depth_limit | false | [APILimitOption](/api-reference/syntax-defs.mdx#apilimitoption) | Restriction based on its depth, preventing deeply nested queries |
|
||||||
|
| node_limit | false | [APILimitOption](/api-reference/syntax-defs.mdx#apilimitoption) | Restriction based on the number of nodes in GraphQL operation response |
|
||||||
|
| time_limit | false | [APILimitOption](/api-reference/syntax-defs.mdx#apilimitoption) | Restricts the time that a GraphQL operation is allowed to take. The duration is specified in seconds |
|
||||||
|
| batch_limit | false | [APILimitOption](/api-reference/syntax-defs.mdx#apilimitoption) | Restricts the number of GraphQL operations in a batched request |
|
||||||
|
| rate_limit | false | [RateLimitOption](/api-reference/syntax-defs.mdx#ratelimitoption) | Restricts number of GraphQL operations per minute |
|
||||||
|
|
||||||
|
In the above metadata spec:
|
||||||
|
|
||||||
|
1. The API Limits are enabled by default, i.e the default value of `disabled` is `false`
|
||||||
|
2. When `disabled` is `false` and none of the API Limits are set then no API limits are applied.
|
||||||
|
3. The `global` field in all the API Limits is mandatory, and is used as the default API limit if no `per_role` option
|
||||||
|
is set for the user.
|
||||||
|
4. The `per_role` can be used to override the `global` API Limit value
|
||||||
|
5. For `rate_limit` if no `unique_params` are provided then, the requests will be rate-limited on the `role_name` i.e
|
||||||
|
the `X-HASURA-ROLE` that is used to issue the request
|
||||||
|
|
||||||
|
## remove_api_limits {#metadata-remove-api-limits}
|
||||||
|
|
||||||
|
You can remove **all** the api limits that have been set using `remove_api_limit` API.
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /v1/metadata HTTP/1.1
|
||||||
|
Content-Type: application/json
|
||||||
|
X-Hasura-Role: admin
|
||||||
|
|
||||||
|
{
|
||||||
|
"type": "remove_api_limit"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -1627,3 +1627,26 @@ Table columns can be referred by prefixing `$` e.g `$id`.
|
|||||||
| -------------- | -------- | ----------------------------- | ----------------------------------------- |
|
| -------------- | -------- | ----------------------------- | ----------------------------------------- |
|
||||||
| event_triggers | true | [[TriggerName]](#triggername) | List of trigger names |
|
| event_triggers | true | [[TriggerName]](#triggername) | List of trigger names |
|
||||||
| source_name | true | [SourceName](#sourcename) | Source to which the Event Triggers belong |
|
| source_name | true | [SourceName](#sourcename) | Source to which the Event Triggers belong |
|
||||||
|
|
||||||
|
## APILimitOption {#apilimitoption}
|
||||||
|
|
||||||
|
| Key | required | Schema | Description |
|
||||||
|
|-----------|----------|-------------------------------|----------------------------------------------------------------------|
|
||||||
|
| global | true | Integer | Mandatory limit to be set at the global level |
|
||||||
|
| per_role | false | Object (`String`: Integer) | Map of role name to limit value. This defines limits for each role |
|
||||||
|
|
||||||
|
## RateLimitOption {#ratelimitoption}
|
||||||
|
|
||||||
|
| Key | required | Schema | Description |
|
||||||
|
|-----------|----------|-----------------------------------------------------------------------|----------------------------------------------------------------------------|
|
||||||
|
| global | true | [RateLimitPerRoleOption](#ratelimitperroleoption) | Mandatory rate limit to be set at the global level |
|
||||||
|
| per_role | false | Object (`String`: [RateLimitPerRoleOption](#ratelimitperroleoption)) | Map of role name to rate limit config. This defines limits for each role |
|
||||||
|
|
||||||
|
|
||||||
|
## RateLimitPerRoleOption {#ratelimitperroleoption}
|
||||||
|
|
||||||
|
| Key | required | Schema | Description |
|
||||||
|
|------------------|----------|-------------------------------|----------------------------------------------------------------------|
|
||||||
|
| unique_params | false | `String` \| [`String`] | This would be either fixed value `IP` or a list of Session variables |
|
||||||
|
| max_reqs_per_min | true | Integer | Maximum requests per minute to be allowed |
|
||||||
|
|
||||||
|
|||||||
@ -188,7 +188,8 @@ query query3 {
|
|||||||
API limits can have a _global_ or _per role_ configuration. If an incoming request does not contain a valid role then
|
API limits can have a _global_ or _per role_ configuration. If an incoming request does not contain a valid role then
|
||||||
the global limit is applied.
|
the global limit is applied.
|
||||||
|
|
||||||
<Thumbnail src="/img/security/pro-tab-apilimits.png" alt="Hasura Cloud Console api limit tab" />
|
<Thumbnail src='/img/security/pro-tab-apilimits.png' alt='Hasura Cloud Console api limit tab' />
|
||||||
|
<Thumbnail src='/img/security/security-apilimits-details.png' alt='Hasura Cloud Console api limit tab details' />
|
||||||
|
|
||||||
:::info Admin & IntrospectionQuery exemptions
|
:::info Admin & IntrospectionQuery exemptions
|
||||||
|
|
||||||
@ -198,105 +199,5 @@ All API limits are **not** applied for the admin role, and depth limits are **NO
|
|||||||
|
|
||||||
## Metadata specification
|
## Metadata specification
|
||||||
|
|
||||||
Hasura provides two Metadata API's to manage API limits
|
This [API Reference Documentation](/api-reference/metadata-api/api-limits.mdx) describes the metadata API structure to manage API limits.
|
||||||
|
|
||||||
### Setting API limits
|
|
||||||
|
|
||||||
You can configure api limits using the `set_api_limits` API.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
type: set_api_limits
|
|
||||||
args:
|
|
||||||
disabled: # Optional Field (Either True or False, The value is False by default)
|
|
||||||
|
|
||||||
depth_limit: # Optional API Limit
|
|
||||||
global: # Mandatory Field
|
|
||||||
per_role: # Optional Field
|
|
||||||
<role_name>: <limit value> # Eg: user: 5
|
|
||||||
|
|
||||||
node_limit: # Optional API Limit
|
|
||||||
global: # Mandatory Field
|
|
||||||
per_role: # Optional Field
|
|
||||||
<role_name>: <limit value> # Eg: user: 5
|
|
||||||
|
|
||||||
rate_limit: # Optional API Limit
|
|
||||||
global: # Mandatory Field
|
|
||||||
unique_params: # Optional Field, Can either be IP Address or Session variables
|
|
||||||
max_reqs_per_min: # Mandatory Field
|
|
||||||
|
|
||||||
per_role: # Optional Field
|
|
||||||
<role_name>:
|
|
||||||
max_reqs_per_min: # Mandatory Field
|
|
||||||
unique_params: # Optional Field
|
|
||||||
|
|
||||||
time_limit: # Optional API Limit
|
|
||||||
global: # Mandatory Field
|
|
||||||
per_role: # Optional Field
|
|
||||||
<role_name>: <limit value> # Eg: user: 5
|
|
||||||
|
|
||||||
batch_limit: # Optional API Limit
|
|
||||||
global: # Mandatory Field
|
|
||||||
per_role: # Optional Field
|
|
||||||
<role_name>: <limit value> # Eg: user: 5
|
|
||||||
```
|
|
||||||
|
|
||||||
In the above Metadata spec:
|
|
||||||
|
|
||||||
1. The API Limits are `Enabled` by default, i.e the default value of `disabled` is `False`
|
|
||||||
2. When `disabled` is `False` and none of the API Limits are set then no API limits are applied.
|
|
||||||
3. The `global` field in all the API Limits is mandatory, and is used as the default API limit if no `per_role` option
|
|
||||||
is set for the user.
|
|
||||||
4. The `per_role` can be used to override the `global` API Limit value
|
|
||||||
5. For `rate_limit` if no `unique_params` are provided then, the requests will be rate-limited on the `role_name` i.e
|
|
||||||
the `X-HASURA-ROLE` that is used to issue the request
|
|
||||||
|
|
||||||
Example Metadata Spec:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
type: set_api_limits
|
|
||||||
args:
|
|
||||||
disabled: false
|
|
||||||
|
|
||||||
depth_limit:
|
|
||||||
global: 5
|
|
||||||
per_role:
|
|
||||||
user: 7
|
|
||||||
|
|
||||||
node_limit:
|
|
||||||
global: 3
|
|
||||||
per_role:
|
|
||||||
user: 10
|
|
||||||
|
|
||||||
rate_limit:
|
|
||||||
global:
|
|
||||||
unique_params: IP
|
|
||||||
max_reqs_per_min: 10
|
|
||||||
per_role:
|
|
||||||
anonymous:
|
|
||||||
max_reqs_per_min: 10
|
|
||||||
unique_params: 'ip'
|
|
||||||
user:
|
|
||||||
unique_params:
|
|
||||||
- x-hasura-user-id
|
|
||||||
- x-hasura-team-id
|
|
||||||
max_reqs_per_min: 20
|
|
||||||
|
|
||||||
time_limit:
|
|
||||||
global: 10
|
|
||||||
per_role:
|
|
||||||
user: 5
|
|
||||||
|
|
||||||
batch_limit:
|
|
||||||
global: 5
|
|
||||||
per_role:
|
|
||||||
user: 2
|
|
||||||
```
|
|
||||||
|
|
||||||
### Removing API limits
|
|
||||||
|
|
||||||
You can remove **all** the api limits that have been set using `remove_api_limit` API.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
type: remove_api_limits
|
|
||||||
args: {}
|
|
||||||
```
|
|
||||||
|
|||||||
BIN
docs/static/img/security/security-apilimits-details.png
vendored
Normal file
BIN
docs/static/img/security/security-apilimits-details.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
Loading…
Reference in New Issue
Block a user