GraphQL API - Basics
Introduction
The GraphQL API is your your primary means to integrate with the Xurrent service. GraphQL provides a syntax to query exactly the data you need and receive that data in a predictable way. It is an open standard and the most modern way of querying APIs that exists for web services.
The QL in GraphQL stands for Query Language. But don’t be mistaken: GraphQL is a client facing query language, not a backend database query language. It specifies precisely how to query and modify the data objects that a web service allows you to consume.
The Graph in GraphQL stands for the idea that in a modern application the objects and their relationships can be represented using a graph of nodes. As an example, think about a Request in Xurrent.
The request is linked to a Requested for Person and to a Team. And the Requested for Person is linked to an Organization. We will see how GraphQL makes it possible to query from the Request through the Requested for Person up to the level of the Organization of that person.
GraphQL is based on the Graph theory a key concept in (discrete) mathematics. In fact, the origin of Graph theory goes back as far as 1736 when the Swiss mathematician Euler was able to prove that it is impossible to resolve the problem of the Seven Bridges of Königsberg.
The Parts of a GraphQL API Request
A GraphQL API request consist of 4 parts:
- the Service URL
- the HTTP Verb (the method)
- The headers
- The data (or body).
The Xurrent GraphQL Service URL
There is one GraphQL Service URL for each Xurrent instance:
- Production environment global:
https://graphql.4me.com/ - Production environment Australia:
https://graphql.au.4me.com/ - QA environment global:
https://graphql.Xurrent.qa/ - QA environment Australia:
https://graphql.au.Xurrent.qa/ - Demo environment:
https://graphql.4me-demo.com/
The HTTP Verb (the Method)
With GrapHQL you will always use the POST method as well for queries as for mutations. There is just one exception to this rule: to list all types in the GraphQL schema, you should use the GET method (see next topic on introspection).
The Headers
Each request to the Xurrent GraphQL API must supply some HTTP headers. The first one is to specify your personal access token:
Authorization: Bearer <personal-access-token>
The second one is to specify the Xurrent account you need access to:
X-Xurrent-Account: <accountID>
Finally you will specify that the request body format is JSON:
Content-Type: application/json
The Data or Body
With GraphQL you will send a GraphQL query string to the web service. That query string will be validated and executed by the web service and the web service will return a response in the JSON format.
The GraphQL query string is to be defined in the data or body part of the request.