This tutorial provides a short introduction to GraphQL terminology and explains how to interact with GraphQL-based APIs.
The GraphQL data query language is:
The documentation in the API reference section are generated from the GraphQL schema. All calls are validated and executed against the schema. The following information determines the data that you can call:
Note that you may need to rely on both the documentation and schema validation to successfully call the GraphQL API.
A field is a unit of data you can retrieve from an object.
The official
GraphQL documentation says:
"The GraphQL query language is basically about selecting fields on objects."
The official specification also says about fields:
"All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response."
This means that if you try to return a field that is not a scalar, the schema validation will throw an error. You must add nested subfields until all fields return scalars.
GraphQL is introspective. This means that you can query a GraphQL schema for details about itself.
__schema to list all types defined in the schema and get details about each query { __schema { types { name kind description fields { name } } } }__type to get details about any typequery { __type(name: "Conversation") { name kind description fields { name } } }Since results are in JSON, we recommend pretty-printing them for easier reading and searching.
Note: The introspection query is probably the only GET request you'll run in GraphQL.
If you're passing a body, the GraphQL request method is POST, whether it's a query or a mutation.
GraphQL's operations consist of multi-line JSON. You can use cURL or any other HTTP-speaking library.
In REST, HTTP verbs determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is POST. The exception is an introspection query, which is a simple GET to the endpoint.
To query GraphQL, we can make a POST request with a JSON payload. The payload must contain a string called query:
http
POST {{BASE_URL}}/partners/{{Partner-ID}}/data/{conversationdata}/getConversationById
Content-Type: application/json
Authorization: Basic {{Client-ID}}:{{Secret}}
x-cp-partner-id: {{Partner-ID}}
x-resource-template-version: {{template-version}}
{ “query”: “query{getConversationById(conversationId:\“39824e66-7eb1-4099-8110-ed41d7793f4d\“){conversationId}}” } Note: The string value of "query" must escape newline characters, or the schema will not parse it correctly. For the POST body, use outer double quotes and escaped inner double quotes.
The two types of allowed operations in GraphQL are queries and mutations. Comparing GraphQL to REST, queries operate like GET requests, while mutations operate like POST/PATCH/DELETE.
Queries and mutations share similar forms, with some important differences.
GraphQL queries return only the data you specify. To form a query, you must specify fields within fields (also known as nested subfields), until you return only scalars.
Queries are structured like this:
query {
JSON objects to return
}For a real-world example, see An Example Query below.
To form a mutation, you must specify three things:
Mutations are structured like this:
mutation {
mutationName(input: {MutationNameInput!}) {
MutationNamePayload
}The input object in this example is MutationNameInput, and the payload object is MutationNamePayload.
Variables can make queries more dynamic and powerful, and they can reduce complexity when passing mutation input objects.
Here's an example query with a single variable:
query($conversationId:String!) { getConversationById(conversationId: $conversationId) { conversationId } } variables { "conversationId": "123" }There are three steps to using variables:
Define the variable outside the operation in a variables object. The object must be valid JSON. This example shows a simple String variable type, but it's possible to define more complex variable types, such as input objects. You can also define multiple variables here.
variables { "conversationId": "123" }Pass the variable to the operation as an argument. The argument is a key-value pair, where the key is the name starting with $ (e.g., $conversationId), and the value is the type (e.g., String). Add a ! to indicate whether the type is required. If you've defined multiple variables, include them here as multiple arguments.
query($conversationId:String!) {Use the variable within the operation. In this example, we substitute the variable for the conversationId to retrieve. We specify a type in step 2 because GraphQL enforces strong typing.
getConversationById(conversationId: $conversationId) {This process makes the query argument dynamic. We can now simply change the value in the variables object and keep the rest of the query the same.
Using variables as arguments lets you dynamically update values in the variables object without changing the query.
Let's walk through a query and put this information in context.
The following query looks up and returns each conversation's conversationId, originatingChannelType and all participants' ids:
query { getConversationById(conversationId:"123") { conversationId originatingChannelType participants { participantId } } }Let's look at the composition line by line:
query {getConversationById(conversationId:"123") {Conversation object. The schema validation indicates this object requires a conversationId as an argument. Now that we know we're retrieving a Conversation object, we can specify the fields we want to return:conversationId originatingChannelType participants { participantId }conversationId, originatingChannelType, and participants fields of the Conversation object.)Note: You may notice that running this query with conversationId 123 won't return anything.
Try running it on with one of the valid conversationIds and you'll likely see a difference.
There is a lot more you can do when forming GraphQL calls. Here are some places to look next: