Yanzi GraphQL API
Yanzi offers a GraphQL API as a complement to our regular Cirrus API. We chose to add a GraphQL API as it offers great flexbility for integrators to efficiently access structured and relational data in the Yanzi Platform.
If you are new to GraphQL, we recommend you take a look at: https://graphql.org/learn/
The best way to learn the Yanzi API is through the GraphiQL console. It has integrated autocomplete and documentation.
Notice! You will be accessing and possibly manipulating your live data in production.
Connecting to the GraphQL API
The GraphQL API can be accessed either through the GraphQL endpoints
wss://eu.yanzi.cloud/graphql respectively, or be
tunneled through the
GraphQLResponse Cirrus messages.
Tunneling is only recommended if you are already talking to Cirrus and would prefer keeping all communication over the same socket. If you will only be using the GraphQL API, then you are better served by the GraphQL endpoint.
Obtaining a sessionId
Unless tunneling through an already authenticated Cirrus connection, a sessionId has to be obtained.
The session id can be reused from an existing Cirrus connection, or be created by sending a POST request to
The body of the POST request allows the same fields as the Cirrus LoginRequest, so either a
password pair or an
1 2 3 4
You should strive to reuse the session id for as long as possible. (Logging in quickly becomes rate-limited)
Option A: Connecting to the GraphQL HTTP endpoint
The HTTP GraphQL endpoint is
You can execute queries by sending them in the body of a POST request to the endpoint.
The requests must be authenticated by setting sending the session ID obtained above in the Authorization header.
Authorization: bearer sessionIdString123.
Option B: Connecting to the GraphQL WebSocket endpoint
The WebSocket GraphQL endpoint is
This endpoint implements the apollo format of GraphQL over WebSockets. This makes the endpoint compatible out of the box with client libraries such as https://github.com/apollographql/subscriptions-transport-ws. Authentication is handled through the initial payload.
1 2 3 4 5 6 7 8 9
Option C: Using GraphQL over Cirrus
Tunneling messages might align better with your existing infrastructure, but will possibly require slightly more effort to integrate with existing graphql tools. Nevertheless messages are wrapped quite simply as show below. Note that the
locationId in the
LocationAddress is required, if specified as
* the request will be terminated on the linkserver.
1 2 3 4 5 6 7 8 9