GraphQL API

Overview

About the GraphQL API

The new iAdvize GraphQL API offers flexibility and the ability to define precisely the data you want to fetch.

One of the power of GraphQL API is to allow you retrieve many resources in one HTTP call and you can request only fields you need.

If you wan to learn more about GraphQL, please check Learn GraphQL.

Also, a lot of GraphQL clients are available in Official GraphQL documentation.

Root endpoint

The REST API has numerous endpoints; the GraphQL API has a single endpoint: https://api.iadvize.com/graphql

The endpoint remains constant no matter what operation you perform.

If your environment is on the SD platform, your endpoint is: https://api.iadvize.com/graphql?platform=sd

Authentication

The iAdvize authentication mecanism uses temporary tokens that has a 24 hours lifetime.

Unlike our REST API, you can generate your own tokens with a user email & password.

⚠️ Please note the following policy on authentication:

• 10 logins per minute per user
• 100 logins per minute per ip address

Read the following articles to learn more about authentication and how to:

• Create an access_token
• Authenticate your API calls
• Check the validity of an access_token

GraphiQL

You can run queries on real iAdvize data using GraphiQL, an integrated development environment in your browser that includes docs, syntax highlighting, and validation errors.

https://developers.iadvize.com/tools/graphiql

Learn how to to use GraphiQL with iAdvize

Reference

Documentation

View reference documentation to learn about the data types available in the iAdvize GraphQL API schema.

See static documentation of our GraphQL types, queries and mutation.

Discovering the GraphQL API

Since graphQL is introspective, it means you can query a GraphQL schema for details about itself.

Query __schema to list all types defined in the schema and get details about each:

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

Query __type to get details about any type:

query {
  __type(name: "Conversation") {
    name
    kind
    description
    fields {
      name
    }
  }
}

GraphQL Voyager

With GraphQL Voyager, you can visually explore the iAdvize GraphQL API as an interactive graph.

This is a great tool that represent all the iAdvize GraphQL API as an interactive graph.

Let's start the journey!

Guides

Create an access_token

You have make a POST call on the following endpoint: https://api.iadvize.com/oauth2/token and send the following parameters:

Parameter	Description	Type	Mandatory
username	User email	String	Yes
password	User password	String	Yes
grant_type	Oauth2 grant type (only password is supported)	String	Yes

⚠️ Please note that parameters must be sent as application/x-www-form-urlencoded

Example:

curl  --request POST \
      --url https://api.iadvize.com/oauth2/token \
      --data "username={EMAIL}&password={PASSWORD}&grant_type=password"

Authenticate your API calls

To authenticate an API call just pass the access token in an authorization header.

curl  --request POST \
      --url https://api.iadvize.com/graphql \
      --header "Content-Type: application/json" \
      --header "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
      --data "YOUR_QUERY"

Check the validity of an access_token

You can verify token validity with the authenticated route below.

curl  --request GET \
      --url https://api.iadvize.com/_authenticated \
      --header "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

If your token is valid, you will receive a response that looks like this:

{
  "authenticated": true
}

If your token is expired or invalid, you will receive the following response:

{
  "error_description": "access token not valid",
  "error": "invalid_token"
}

Forming queries with GraphQL

Because GraphQL operations consist of multiline JSON, we strongly recommend using the GraphiQL tool to make GraphQL calls. But, you can also use cURL or any other HTTP-speaking library.

While with REST we use HTTP verbs to define the operations to perform, in GraphQL we will use the HTTP POST verb, because you will provide a JSON-encoded body whether you are performing a query or a mutation.

Here is an example to list all the projects :

curl  --request POST \
      --url https://api.iadvize.com/graphql \
      --header "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
      --header "Content-Type: application/json" \
      --data "\
      { \
        \"query\":\"{ \
          routingRule(id: \\\"10ba02f1-ec5c-4687-a10a-e7871ee72903\\\") { \
            availability { \
              chat { \
                isAvailable \
              } \
            } \
          } \
        }\" \
      }"

⚠️ Note: The string value of "query" must escape quotes and backslashes characters or the schema will not parse it correctly.

Using GraphiQL

Execute GraphQL queries

• Create an access_token
• Open the GraphiQL tool
• In the header section, add a new Key Authorization (if it does not already exists).
• Then, in the Value field, enter Bearer <token>, where <token> is the token you generated previously. ⚠️ Don’t forget to check the box to enable the header
• and here we go!

You can test your access by querying your projects:

query {
  projects {
    edges {
      node {
        id
        name
      }
    }
  }
}

The sidebar docs

The collapsible Docs pane on the right side of the Explorer page allows you to browse documentation about the type system.

All types in a GraphQL schema include a description field compiled into documentation that is automatically updated.

The Docs sidebar contains the same content that is automatically generated from the schema under Reference. It is just formatted differently.

Using the query variables pane

If you want to learn more about variables in GraphQL you can read this documentation : https://graphql.org/learn/queries/#variables