mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 01:12:56 +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 |
|
||||
| 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
|
||||
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
|
||||
|
||||
@ -198,105 +199,5 @@ All API limits are **not** applied for the admin role, and depth limits are **NO
|
||||
|
||||
## 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