.svg){kind=small}
GraphQL is a query language for reading and mutating (changing) data via an API. Unlike a REST API, GraphQL does not rely on pre-defined endpoints. GraphQL queries, similarly to SQL queries, can individually be customised down to each element of a data schema, which in our case is the Auto API schema. GraphQL queries are, in most cases, faster than REST API calls and offer greater flexibility to developers of all kinds of services and applications.
GraphQL is designed to break down data from different sources depending on the incoming queries. It is perfectly suited for the Auto API package, an open data protocol for vehicle data coming from many different vehicle manufacturers and their vehicles. Because there is no single technical categorisation or bundling that can fit all brands and their specific implementations, any rugged API definition would eventually cause inconveniences.
Since we have been using GraphQL internally for some time and because we have seen how well it works when working with granular data structures, we had the idea to offer it to the users of our platform as well.
Example queries
One feature we make use of is the GraphiQL library, which is an interactive console to compose and test different queries. The backend will always respond with the respective and correct test values. Once you have perfected your query in the console, you can just add your authorisation headers and call an actual car via our live API or our car simulator via our sandbox API.
Let’s have a look at a few examples: In this first query, we retrieve the current battery level of an electric vehicle together with the unit of measurement and the timestamp. It’s a simple query with a straightforward response:
Next, we could of course keep adding other charging related data points to the query, such as electrical range, plugged in status or battery health. As we are not limited to a specific data category, however, we can also ask for any other information that we are interested in. Let's go ahead and add location data to the query.
Now we also got the latitude and longitude coordinates in the response, although the endpoint has remained exactly the same.
A useful feature of the GraphQL API is that it’s easy to inspect the data schema interactively. One way, of course, is to look at the documentation pages and then write queries, another is to compose queries intuitively. The console supports such an approach neatly with an autocomplete function.
Feel free to go ahead and try it out yourself to get a feel for it. You can find a complete list of all available data points of the Auto API on Airtable.
Vehicle dashboard sample app
As with all of our APIs and SDKs, we strive to provide as many example implementations as possible to kick-start your integration process. With the GraphQL API, we have taken it a step further by not only providing a code repository as a reference, but a fully functional vehicle dashboard that can be deployed to Heroku with one click.
You can find our sample app on GitHub. If you prefer to run it locally, you can follow the README instructions to set it up in localhost.
Here is a breakdown of the dashboard features:
Written as a Node.js webapp
Configure your application credentials through the user interface
Full integration of the consent flow to enable access
Add as many vehicles as you like, all of which are persisted between sessions
Visualises data that is fetched from the car simulator or vehicle
Show data in grid view, list view or a map view
Filter properties based on your needs and configure the refresh rate
We are positive that the dashboard sample application can be useful not only for developers but also for anyone who wants to test telematics data from test vehicles.
Further reading
The best place to learn about the GraphQL API is our documentation. Here you will find all technical guidance along with a tutorial on how to register your application on our platform in order to gain API credentials.
We are curious to see how you will use the GraphQL API. If you have any further questions or if you would like to schedule a personal demonstration, we look forward to hearing from you.
