GraphQL API
The ALOR Broker trading system provides access to aggregated reference data via the GraphQL API.
This method of interaction allows for flexible control over the response structure by requesting only the object attributes necessary to solve the task at hand.
Interface Features
GraphQL is based on the use of a strictly typed schema and a single endpoint for all query types. This allows information from various sources to be aggregated within a single request.
This interaction model has its advantages and disadvantages in practical use of the interface.
| Advantage | Disadvantage |
|---|---|
| The ability to independently define the composition of fields in the response reduces redundant traffic | Requires prior study of the GraphQL schema to correctly formulate queries |
| Retrieving related data from different entities in a single request eliminates the problem of multiple requests (n+1) | Increased complexity of request formation compared to fixed HTTP API structures |
A single point of interaction (/hyperion) simplifies network configuration and integration | No native caching of responses at the HTTP protocol level due to the use of the POST method |
| Strict parameter typing and schema transparency allow for automatic client-side validation of requests | Processing complex nested requests can place increased load on server computing resources |
Currently, no specific quantitative restrictions have been set for the GraphQL API by security subsystems; however, when working with the interface, you should be guided by the principles of common sense and fair use.
Use Cases
The GraphQL API is most effective for tasks that require retrieving comprehensive reference information. Below are examples of use cases for this interface:
| Acceptable | Unacceptable |
|---|---|
| Retrieving aggregated information about a security: company description, dividends, and coupons in a single request | Attempting to use GraphQL for high-frequency monitoring of rapidly changing quotes |
| Generating custom data selections for display in front-end applications and personal accounts | Downloading complete historical archives of market data spanning several years |
| Searching for and filtering instruments based on complex criteria not available in standard HTTP API methods | Sending simple, uniform requests that have direct equivalents in the HTTP API, without the goal of data aggregation |
| Working with data coming from multiple internal subsystems in real time | Mass duplication of requests to immutable reference tables within a single trading session |
To obtain the most up-to-date data on trading progress and the state of the order book, use the WebSocket API; for specific data and order operations, it is better to use the HTTP API.
Recommendations
To ensure stable interactions and optimize performance, follow these guidelines:
- Minimize the data you retrieve. Only request the fields that are directly used in your algorithm or interface.
- Use variables. Pass dynamic query parameters (such as tickers or identifiers) via
variablesrather than embedding them directly in the query string. - Study the schema. The GraphQL schema is always available for review at
https://api.alor.ru/hyperion(Production) andhttps://apidev.alor.ru/hyperion(Test environment). Use GraphQL-compatible API clients (the Playground linked above or Postman) to test your requests beforehand. - Stay up to date. Unlike the HTTP API and WebSocket API, updates to the GraphQL schema are not recorded in the changelog. If you have saved the schema locally, check the source periodically for changes.
- Cache the result. If you’re fetching data that rarely changes (e.g., a dividend calendar), store it locally on your application’s side.
Combine all available system interfaces to solve your tasks as efficiently as possible.