Documentation of limitations of the API
Rate Limiting
While the GraphQL API can be used by any FlightLogger user without any charge, there are limits to the amount of API calls users may perform (i.e. the rate of usage). Performing an excessive amount of calls to the API may cause your requests to be rate limited.
Rate limiting refers to the act of denying API requests from a user based on their usage of the API. The FlightLogger GraphQL API has a lenient rate limiting policy in place. The rate limiting restriction is meant mainly to discourage overuse and abuse of the API. During normal, well-considered usage of the API, you should never experience being rate limited.
When rate limited, any request made to the API will result in a HTTP response with the status code 429 Too Many Requests. The payload of the response will contain a small message indicating why the request has been denied, formatted as JSON. Most importantly, the response to a rate limited request will contain the Retry-After header, which tells you how many seconds you'll have to wait before making another request without being rate limited.
It should be noted that rate limited requests (i.e. those responded to with the 429 status) also count towards the rate limitation. This means simply retrying denied requests immediately after they fail is not a viable strategy, as you will continue to be rate limited. The Retry-After header should be used to avoid this.
While FlightLogger users may create and use multiple API keys simultaneously (see the Getting Started article), rate limiting is based on users, not keys. This means using multiple API keys does not increase the amount of requests that can be made by the user.
Being rate limited incurs no long-term penalty for the rate limited user, within reason.
Complexity & Depth Limitations
In addition to rate limiting, the GraphQL queries sent to the API have a few semantic restrictions placed upon them, namely complexity and depth.
Depth restriction dictates the maximum depth of the GraphQL queries accepted by the API. Depth is the concept of nested layers selected in the types and fields of the GraphQL schema. Every level of nesting constitutes an increase in depth. Example query:
bookings { <- depth 1
registration { <- depth 2
pic { <- depth 3
callSign <- depth 4, etc...
}
}
}
The depth restriction should not be encountered in regular use-cases, but rather, exists to discourage selecting circular dependencies, example:
booking {
registration {
booking {
registration {
...
}
}
}
}
Complexity restriction dictates to total amount of fields a query may select. Each field in the schema has a complexity which, when selected in a query, will count towards to total complexity of a query. If the sum of all the complexities of the fields selected in a query exceed the maximum allowed complexity, the query will be rejected.
Prevention
In the case of both depth and complexity limitations, these can be worked around by preferably re-working/re-thinking the strategy with which the API is used, otherwise by splitting the query up in multiple requests.