Three graphQl pillars: queries, mutations, subscriptions

Important: Before starting you must be a user with the appropriate user roles to access the API Keys section within the InControl Portal.

These Roles Include:

• Advanced Admin
• Admin + API 

In the previous article we executed a graphQl query in Postman. As subscriptions are problematic to perform in Postman, we suggest you use web-client GraphiQl to perform more complicated operations. You will also need this link to search for schemas.

Note: If you're logged into the InControl application that is indicated in the URL field, your requests will be executed on behalf of the user logged in there. Despite or otherwise you will need to add a new Header named 'Authorization' with Value 'Bearer <ClientId>:<ClientSecret>'. To learn how to get Client Id and Client Secret visit our 'How to Set up API Keys' article. 

The simplest and most harmless of them all. The only thing it does is gets data. The best thing about graphQl is that if you only want to know one thing about an object (let's say, a person's name), you won't be overwhelmed with other irrelevant things like occupation, hobbies, their favorite movie or zodiac sign. 

Generally speaking it is an update. With mutations you can create you person a child, update their outfit or delete a leg, so be careful: some updates cannot be undone. Mutations will always require arguments, unlike queries, to know exactly which person you want to mutate.

What do we do when we like someone? Right, subscribe for updates (legal stalking). Having subscribed for updates, you will catch up on updates in real-time.

For the mutation example we will create a new Vehicle. Please, find this mutation schema in Documentation Explorer on the right. The syntax for mutations is as follows:

As you could have noticed, not all arguments in the list are used, only marked with an exclamation sign. We used only required arguments, while others listed (without exclamation mark) are optional. Arguments list contains information about argument name, argument type and description. The last part in curly brackets is what we want to return. In this case, it's a set of Vehicle fields - they are also optional and required. 

After completing the mutation, hit the Play button (Execute Query (Ctrl-Enter)). Response (positive or negative) will be displayed on the right side. Note that if some part of the Request is underlined in red, it contains syntaxis mistakes or you have missed or overused some brackets. 

Subscriptions require 2 more steps: getting a subscription token and setting it up.

As a result, subscriptionToken is returned. Now Copy it. 

The next step will be to alter the WS URL field value to this: wss://<applicationendpoint>/api/subscriptions?token=<subscriptionToken>.

chargerStatusUpdates has only one argument ids: [IntId!] ! . The following example demonstrates another way of forming graphQl operations - with using variables (those with $ sign). No matter if you separate the variables from the query, it's a matter of taste and usability.  

And here are graphQL vars:

After executing 'Your subscription data will appear here after server publication!' will appear. This means, when charger statuses change, data you requested will appear right away here. To test this, you can run one of the chargers. 

And now the least peculiar - rawEventUpdate subscription, which description states: 'Subscribe to raw event changes'. In fact, it's what we call 'Debug real-time mode' located in Manage mode on Charger Page.

Here is where your charger id could be.

New rawEvents appear right after server publication (provided requested charger is running).

If you see something scary like this 'Error: [object Object]' this means that you've either requested wrong id or you simply lack permissions. In this case, check your Role, Application and Account scope of the API Key or charger id. Unfortunately, this web-client does not support some websocket things we use to show pretty and comprehensive error messages. But if you really do need to, there's a way out - to catch the error in dev tools.