GraphQL API Tutorial

The GraphQL Auto API enables flexible querying of specific Auto API datapoints, allowing you to specify the data you are interested to read in a granular way. This tutorial will help you get started step by step.

GraphiQL Console

Introspect the Auto API schema easily with the GraphiQL console.

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 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
      }
    }
  }
}

Inspection can also be done with cURL as shown here:

curl 'http://graphql-api.high-mobility.com' -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer JWT_TOKEN' \
    -d '{ "query": "query { __schema { types { name kind description fields { name } } } }" }'

Create a Cloud App

In the Develop tab you will find your 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 Develop tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
  2. In the left section, select the permissions that your app needs under the "Permissions" tap. For the purporses of this tutorial, you will need to select the "Diagnostics" capability and then select "Get odometer" before pressing "save".
    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 carmaker workspaces you will be able to create vehicles or other items to link with your app and to test with the emulators.

  1. Go to a carmaker workspace in the left navigation menu, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
  2. You will find the vehicle capabilities listed to the left.
  3. If you click on the "Launch emulator" button you will see how it looks like. Next we will need to link an app with the vehicle.

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 the Apps tab, 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.

The config variable will look something like this:

const GRAPHQL_CONFIG = {
  "version": "2.0",
  "type": "graph_ql_api",
  "private_key_id": "4ea88039-ad8d-4ad6-98f3-dfa732cc3df7",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgpXy8b0STpG2cZoOI\n/QBCwAglm05jynlisjzgr8tf0gihRANCAARr/0RviZRZRXs+g5lqUctZPfgLEleG\nalv0rKPlN2Z+ztHuOEdukOTFyQnOCx3R/yEwHtxckiO9hOwIzfpzHiIp\n-----END PRIVATE KEY-----",
  "app_uri": "https://sandbox.graphql-api.high-mobility.com/v1",
  "app_id": "32CA6F235A5B9804D154EF07",
  "client_serial_number": "53C441983C0A4C8A86"
}

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:

verThe version of the API, taken from the version in the config
issThe application client serial number, taken from the client_serial_number in the config
audThe API URI, taken from the app_uri in the config
iatThe current datetime, formatted in the Unix timestamp format. This is used to minimize the possibilities of a replay attack, so that a JWT created in the past cannot be reused. Currently a tolerance of 30 seconds is used to account for any clock skew between our servers and the back end servers, but it can be changed, probably shortened in the future. Example value: 1502121268
jtiAn unique identifier in the UUID format of the JWT itself to ensure a JWT can be used only once.
subThe access token specific to the car, the retrieal of which is done per the next step or by the OAuth2 or Fleet Clearance flows

Send a Request

Once the emulator is open, fire away a request. For example to get the odometer of the vehicle. Note that you will get a "Vehicle Asleep" error returned if the emulator is closed.

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.

curl 'http://graphql-api.high-mobility.com' -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer JWT_TOKEN' \
    -d '{ "query": "query getOdometer { diagnostics { odometer { data { value unit } } } }" }'