Skip to main content

GraphQL API Definitions

When not using Dashboard for configuration, the API Definitions are going to be read from the apis_path specified in gateway.json.

Each file in that directory (either json or yaml) represents a GraphQL API, which in turn may have 1 or more data sources.

Configuration options#

The only required options of the file are name (name of the API) and endpoint (on which endpoint is it going to be available):

"name": "My First API",
"endpoint": "/my-first-api"

In fact, a GraphQL API can have 0 data sources but... that doesn't make a lot of sense in practice.

In order to add the data-sources to our API we have to specify the source_config_names option:

"name": "My First API",
"endpoint": "/my-first-api",
"source_config_names": ["my-data-source.yaml"]

Only the file name is required, the path is going to be resolved from the sources_path option in gateway.json.

Read more about configuration of data sources.

Below is the list of all available configuration options.


Name of the API. It is mainly used for logging purposes.


A unique endpoint of this API. Should start with "/".


Optional. Contains a list of filenames (with json or yaml extension) of data-sources which should be included into the API.


Optional. Type of value โ€“ number. When set to a number bigger than 0, it will rebuild the GraphQL Schema of the API in the specified intervals (in milliseconds).

This can be used to rebuild (in regular intervals) the federated schema for the underlying microservices. If during the rebuild phase at least one of the data-sources returned an error, the schema is not going to be rebuilt, and the old schema will continue to be served on the endpoint.


Optional. Boolean. Defaults to false. When enabled, allows the rebuilding of the schema via control api.


Optional. Boolean. Defaults to false. When enabled, allows the invalidating of the cache via control api.


Optional. Boolean. Defaults to false. When enabled, switches on the IP Filtering middleware which is configured in a way of allow_ips and deny_ips lists.


allow_ips list has a priority over the deny_ips list. It means, that if both lists are specified in the configuration, then only allow_ips values are going to be used.

Examples of configuration:

Allow a single IP
"enable_ip_filtering": true,
"allow_ips": [""]
Deny a range of IPs
"enable_ip_filtering": true,
"deny_ips": [""]
Specify both allow and deny, allow will always take precedence and deny will be ignored
"enable_ip_filtering": true,
"allow_ips": [""],
"deny_ips": [""]


Optional. This value specifies an HTTP Request size limit for a particular API Definition. Accepts numeric (in bytes) or string values. When string is used, the following abbreviations are used:

  • b for bytes
  • kb for kilobytes
  • mb for megabytes
  • gb for gigabytes
  • tb for terabytes
  • pb for petabytes.


Optional. Numeric value that specifies a maximum query depth limit for a given API Definition. Default value is 10.


Optional. Numeric value that specifies a maximum complexity for a request. Defaults to 1000.


Optional. An object with two settings: complexity, which specifies a total request complexity and per, which stands for a rolling time window in seconds.

Example of a configuration:

"rate_limit": {
"complexity": 10000,
"per": 3600


Optional. An object with two fields:

  • auth_header_name โ€“ name of the header from which the authentication token is going to be extracted;
  • auth_tokens โ€“ an array of strings that correspond to token names.

Due to security reasons we do not recommend specifying auth_tokens directly in the configuration file but rather pass them through the environment variables (separated by coma) by setting auth_tokens to @@AUTH_TOKENS.