Skip to content

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.

Note

If you are new to GraphQL, we recommend you take a look at: https://graphql.org/learn/

Explore

The best way to learn the Yanzi API is through the GraphiQL console. It has integrated autocomplete and documentation.

Warning

Notice! You will be accessing and possibly manipulating your live data in production.

Access the GraphiQL Console

Connecting to the GraphQL API

The GraphQL API can be accessed either through the GraphQL endpoints https://api.yanzi.se/graphql andwss://api.yanzi.se/graphql respectively, or be tunneled through the GraphQLRequest and 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 https://api.yanzi.se/login. The body of the POST request allows the same fields as the Cirrus LoginRequest, so either a username/password pair or an accessToken.

{
    "username": "user@example.com",
    "password": "password"
}

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 endpoint

Note

The HTTP GraphQL endpoint is https://api.yanzi.se/graphql

Connections to the HTTP endpoint are authenticated with a session id specified in the Authorization header: Authorization: bearer sessionIdString123. As long as HTTP headers can be specified, or at least the Authorization header, this endpoint should support most available libraries for GraphQL communication. If this seems to not be the case, please contact mattias@yanzi.se.

Option B: Connecting to the GraphQL WebSocket endpoint

Note

The WebSocket GraphQL endpoint is wss://api.yanzi.se/graphql

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.

let subscriptionsClient = new SubscriptionsTransportWs.SubscriptionClient(
    "wss://api.yanzi.se/graphql",
    {
        reconnect: true,
        connectionParams: {
            sessionId: "YW5kcmVhcy5tYXJ0ZW5zc29...MDYY4MTc1NjY3Njg0OA__"
        }
    }
);

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.

{
    "messageType": "GraphQLRequest",
    "locationAddress": {
        "resourceType": "LocationAddress",
        "locationId": "418131"
    },
    "query": "{ account(accountNumber: $an) { name } }",
    "vars": "{\"an\": \"123\"}"
}
Back to top