Getting started with GraphQL

Introduction to GraphQL

The GraphQL data query language is a powerful way to access vehicle data from our platform. At its core, it enables you to:

• Query datapoints you are interested in and no more.
• Reduce the number of requests by unifying them into a single one.
• Use a strong type system that allows you to only ask for data that is possible to return.
• Work with clear and helpful errors for mistyped queries.
• Use introspection - a GraphQL client can query the schema dynamically.
• Match returning JSON easily with the query.

Endpoint URL

Note that the GraphQL URL is https://sandbox.graphql-api.high-mobility.com/v1 when working with the car emulators and https://graphql-api.high-mobility.com/v1 for cars in production mode.

When you use the configuration snippets from the platform as shown in this tutorial, you will always be using the right URL automatically.

Auto API schema

The GraphiQL console enables discovery and inspection of the GraphQL schema.

Every query that you make in the console is validated and executed against the same schema as the production version. It's possible to query all available datapoints in the Auto API spec and static fixtures are returned.

The GraphQL schema can be inspected with any client-side library by running the query:

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Access to vin and brand is available through a universal capability in the GraphQL schema, an can be fetched with the following:

query {
  universal {
    brand { data }
    vin { data }
  }
}

Limitations

GraphQL does not support fetching Firmware Version, Historical, Multi Command and Vehicle Status capabilities - support for the first 2 might be added in the future, the latter 2 are made redundant by GraphQL's granual query.

Create a Cloud App

In "Develop mode" you will find your sandbox apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. Let's see how to create a new app.

1. Go to the Build tab, select "Develop mode" and click the big plus (+) button, select "Fleet" or "Driver" as the type and then select "Cloud App".
2. In the left section, select the permissions that your app needs under the "Permissions" tap.
   Note: Each permission must be manually added to each new app.
3. You can edit your app name and image from the menu icon next to the app name.

Create a Vehicle

In the "Simulation studio" you are able to create vehicles to link with your app and to test with the simulators. Go to the simulation studio and click the big plus (+) button.

Get API Config

The first thing your app code needs to do is to provide credentials to the server. This is done through JWT and we are showing an example in this tutorial for JavaScript.

1. Go to Develop mode, and select the app you created in the previous steps.
2. Choose "Client certificate" in the left section and then the "GraphQL" tab.
3. Copy the JSON snippet.
4. Insert the snippet into into your project and assign it to a variable.

Here's an overview of the steps:

1. Include the key-pair information in your back-end system. You can use your preferred JWT library.
2. Create an JWT Token per example below.
3. Use the generated JWT Token as a header in each request together with the following content type and accept headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer JWT_TOKEN

Create a JWT

The JWT should be signed using the ES256 algorithm and must contain the following claims:

Link Vehicle and Retrieve Access Token

Now you will need to retrieve an Access Token for the simulator. The technical process differs from fleet apps and apps that are built for individual vehicles owners, drivers.

• Follow the Fleet Clearance tutorial steps for fleet vehicles. You can get the VIN of the simulator from its log console.
• To perform a driver consent, implement the OAuth2 API and initiate the consent flow. Here's an article for doing this using Postman.

Send a Request

Once the simulator is open, fire away a request. For example to get the odometer of the vehicle.

If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your query.

Further Reading

Check out the GraphQL Reference for all details.