API limits¶

Introduction¶

Limiting the depth and/or rate of API requests can help prevent API performance issues caused by malicious or poorly implemented queries.

Configuring an API limit¶

Rate limits

Restricts number of GraphQL operations per minute. This uses a sliding window approach. This means whenever Hasura Pro receives a request, it will count the rate of that client starting from the current time to last one minute.

By default, the rate-limit happens on the role_name i.e the value provided in X-HASURA-ROLE. But you can also combine additional unique parameters for more granularity.

The Unique Parameters that are provided are:

1. IP Address
2. Session Variables

You can choose any one of the above parameters to rate limit the requests.

Note: If you set an Unique Parameter then the combination of both the role_name and the Unique Parameter will be used to rate-limit requests.

Example:

If you rate-limit using the role_name and set the unique parameter for the rate-limit as IP Address, then rate-limit will be applied depending on both those parameteres. i.e If the requests come from a different role but same IP address will NOT be rate limited

Depth limits

Restricts a GraphQL operation based on its depth, preventing deeply nested queries.

Node limits

Restricts a GraphQL operation based on the number of nodes. This helps in limiting the number of different pieces of related data to be fetched.

A node is defined as a field with a selection set.

For example, in the below query the number of nodes is 3 and they are author, articles and homepage_entries.

{
  author {
    name
    articles {
      id
      title
    }
  }
  homepage_entries {
    article_id
  }
}

API limits are defined by role (anonymous, user) and can restrict request rate, depth, or both. Unique request parameters can include IP address or session variables (x-hasura-user-id, x-hasura-org-id, etc.)

Manage API limits¶

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.

Metadata Specification¶

Hasura provides two metadata API’s to manage API limits

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

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

type: remove_api_limits
args: {}