DIMO GraphQL Basics

Constructing a GraphQL Query

To construct a GraphQL query, try out the interactive playgrounds for either the Identity API or the Telemetry API to explore the nodes and how each resources are connected. To understand how GraphQL queries are constructed, please check out this tutorial below:

HowToGraphQL - Core Concepts (Fast-forwarded to GraphQL queries)

Sample Query

Here's a sample query trying to fetch for a vehicle with a tokenId of 21957. Here, I'm naturally specifying what information I want returned from the API, namely the id of the vehicle, aftermarketDevice information, syntheticDevice information, and definition for the selected vehicle:

query {
  vehicle (tokenId: 21957) {
    id
    aftermarketDevice {
      tokenId
      address
    }
    syntheticDevice {
      address
      tokenId
    }
    definition {
      make
      model
      year
    }
  }
}

Alias

For each resource or data field, you can assign an alias of your choice to format the response payload you receive. The following example shows how to rename a data field of powertrainType into alias1:

query {
  signals(tokenId: 22783, interval: "24h", from: "2024-06-25T09:21:19Z", to: "2024-06-29T09:21:19Z") 
  {
    speed(agg: MED)
    alias1: powertrainType(agg: RAND)
    alias2: powertrainRange(agg: MIN) 
    alias3: exteriorAirTemperature(agg: MAX)
    timestamp
  }
}

The response payload is formatted with the aliases, saving developers a few steps in data wrangling:

{
  "data": {
    "signals": [
      {
        "speed": 65.5,
        "alias1": null,
        "alias2": null,
        "alias3": 60,
        "timestamp": "2024-06-28T00:00:00Z"
      }
    ]
  }
}

Sending a GraphQL Query

To send a GraphQL query, simply send your formatted request to {baseUrl}/query and a response will be returned to you.

Sample Payload

This is a sample payload of what I attempted to fetch for in Sample Query:

{
  "data": {
    "vehicle": {
      "id": "V_kc1VxQ==",
      "aftermarketDevice": {
        "tokenId": 13986,
        "address": "0xDDF4C4eC0023d957f4DbEFeBbD158bF6E01bE8c8"
      },
      "syntheticDevice": {
        "address": "0x2A23E35Aa76C95Eb0E29849eC4F874771ad13402",
        "tokenId": 16494
      },
      "definition": {
        "make": "Lexus",
        "model": "NX",
        "year": 2021
      }
    }
  }
}

Paginating through GraphQL Payload

When returning a GraphQL payload that consists of multiple results, such as vehicles or manufacturers, there may be times where the length of the payload is too long for your current operation to display - this is when pagination is needed. To paginate through the results returned, look for the pagination fields listed below under pageInfo.

Field	Type	Description
startCursor	String	Indicates the starting cursor identifier of this current list of results.
endCursor	String	Indicates the ending cursor identifier of this current list of results.
hasPreviousPage	Boolean!	Indicates whether or not a previous page exists. To be used with before.
hasNextPage	Boolean!	Indicates whether or not a next page exists. To be used with after.

Sample Query

{
    vehicles(first: 5) {
        nodes {
            id
            name
        }
        pageInfo {
            startCursor
            endCursor
            hasPreviousPage
            hasNextPage
        }
    }
}

Sample Payload

{
    "data": {
        "vehicles": {
            "nodes": [
                {
                    "id": "V_kc2lUw==",
                    "name": "father chimney abandon"
                },
                {
                    "id": "V_kc2lUg==",
                    "name": "famous chimney abandon"
                },
                {
                    "id": "V_kc2lUQ==",
                    "name": "faculty chimney abandon"
                },
                {
                    "id": "V_kc2lUA==",
                    "name": "expose chimney abandon"
                },
                {
                    "id": "V_kc2lTw==",
                    "name": "exile chimney abandon"
                }
            ],
            "pageInfo": {
                "startCursor": "NDIzMjM=",
                "endCursor": "NDIzMTk=",
                "hasPreviousPage": false,
                "hasNextPage": true
            }
        }
    }
}