Important! Yanzi IoT product line will be sunsetted end of 2025. Click here to learn more.

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.

Production Data

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://eu.yanzi.cloud/graphql andwss://eu.yanzi.cloud/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.

API Limitations

At the moment, it is not possible to do deep queries across multiple locations. Please list locations in a separate call and access them individually.

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://eu.yanzi.cloud/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 HTTP endpoint

Note

The HTTP GraphQL endpoint is https://eu.yanzi.cloud/graphql

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. Example: Authorization: bearer sessionIdString123.

Option B: Connecting to the GraphQL WebSocket endpoint

Note

The WebSocket GraphQL endpoint is wss://eu.yanzi.cloud/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://eu.yanzi.cloud/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\"}"
}