Develop with GraphQL
GraphQL is a query language and runtime for APIs; it provides a more efficient, powerful, and flexible alternative to traditional REST APIs. Unlike REST APIs that have multiple endpoints for different resources, GraphQL uses a single endpoint where you specify exactly what data you need. Whereas with REST APIs, you may need to make several calls to get the information you need, with GraphQL, you need to make only one query.
Your GraphQL endpoint is https://tenant-name.is.here.io/here/api/graphql
For example, with a REST API, you may need to call:
GET /users/123
GET /users/123/posts
GET /posts/456/comments
With a GraphQL API, you need to query only this:
query {
user(id: "123") {
name
email
posts {
title
comments {
text
author
}
}
}
}
The above example is generic. It does not reflect HERE APIs.
Schema
The GraphQL schema is the contract that defines the structure, capabilities, and rules of a GraphQL API. It serves as the single source of truth that describes what data can be queried, how it can be modified, and what types of real-time subscriptions are available.
You can get all the information you need to query the HERE GraphQL API with introspection.
Introspection
GraphQL introspection allows you to query a GraphQL schema to discover what queries, mutations, subscriptions, types, and fields are available. It's essentially a way to ask a GraphQL API "what can you do?" and get a detailed response about its capabilities.
GraphQL schemas are self-documenting through a special set of fields and types that are automatically added to every GraphQL schema. The most important introspection fields are:
- __schema - Returns information about the entire schema
- __type(name: String!) - Returns information about a specific type
- __typename - Returns the name of the current object's type
Introspection queries always begin with two underscores.
query {
__schema {
types {
name
kind
description
}
}
}
query {
__type(name: "User") {
name
kind
fields {
name
type {
name
kind
}
description
}
}
}
query {
__schema {
queryType {
name
fields {
name
args {
name
type {
name
}
}
}
}
mutationType {
name
}
subscriptionType {
name
}
}
}
Example queries and returns
HERE GraphQL queries return JSON.
Example 1
query Contents {
contents {
totalCount
edges {
cursor
node {
uuid
id
name
type
active
customLabel
groups(directOnly: false) {
totalCount
edges {
node {
uuid
id
displayName
description
metadata
revoked
}
}
}
}
}
}
}
{
"data": {
"contents": {
"totalCount": 16,
"edges": [
{
"cursor": "eyJpZCI6ImZhODc0NDc0LWYwYmMtNDMyNS1hZGVkLTUzN2Y4MTdhZTM1ZCJ9",
"node": {
"uuid": "fa874474-f0bc-4325-aded-537f817ae35d",
"id": "salesforce",
"name": "Salesforce",
"type": "WEB",
"active": false,
"customLabel": null,
"groups": {
"totalCount": 1,
"edges": [
{
"node": {
"uuid": "b416ae4b-a6a4-4c9d-9863-9aa6aa1e4474",
"id": "all-users",
"displayName": "All Users",
"description": "This group contains all users that will be accessing resources in this organization.",
"metadata": {
"meta": "data"
},
"revoked": false
}
}
]
}
}
},
{
"cursor": "eyJpZCI6ImQ1NzkwYWVkLWYyNTUtNGM5NS04ZGRmLTJkYTJmNjcyZmMzMyJ9",
"node": {
"uuid": "d5790aed-f255-4c95-8ddf-2da2f672fc33",
"id": "here-transforming-enterprise-productivity",
"name": "HERE | Transforming Enterprise Productivity",
"type": "WEB",
"active": true,
"customLabel": "here-custom label",
"groups": {
"totalCount": 1,
"edges": [
{
"node": {
"uuid": "957cb533-6924-4d5b-ad84-92dca3d41511",
"id": "bbc-home",
"displayName": "BBC - Home",
"description": "",
"metadata": {},
"revoked": false
}
}
]
}
}
},
...
Example 2
query Users {
users {
totalCount
edges {
node {
uuid
id
firstName
lastName
email
active
content {
totalCount
edges {
cursor
node {
uuid
id
name
type
active
customLabel
}
}
}
roles {
totalCount
edges {
cursor
node {
uuid
id
displayName
description
metadata
revoked
}
}
}
}
}
}
}
{
"data": {
"users": {
"totalCount": 7,
"edges": [
{
"node": {
"uuid": "1375d728-9fe2-4e9d-8b9b-809f1e29d2cb",
"id": "john.smith+1@here.io",
"firstName": "John",
"lastName": "Smith",
"email": null,
"active": true,
"content": {
"totalCount": 16,
"edges": [
{
"cursor": "eyJpZCI6IjUwNTkxYTMwLTRjMzMtNDhhOC05ZGNjLTRjZWQ2YjU3YTE1MyJ9",
"node": {
"uuid": "50591a30-4c33-48a8-9dcc-4ced6b57a153",
"id": "here-transforming-enterprise-productivity",
"name": "HERE | Transforming Enterprise Productivity",
"type": "WEB",
"active": true,
"customLabel": null
}
},
{
"cursor": "eyJpZCI6IjU4MzExY2YwLTc3ZDYtNGU5OC04ODFiLWFlZjQ3NWY4NTZhZCJ9",
"node": {
"uuid": "58311cf0-77d6-4e98-881b-aef475f856ad",
"id": "bbc-home",
"name": "BBC - Home",
"type": "WEB",
"active": true,
"customLabel": null
}
},
...