Overview of GraphQL
The monday.com API is built with GraphQL, a flexible query language that allows you to return as much or as little data as you need. It's important to know that GraphQL is an application layer that parses the query you send it and returns (or changes) data accordingly.
Unlike REST APIs where there are multiple endpoints returning different data, GraphQL always exposes one endpoint and allows you to determine the structure of the returned data.
The result of each query will be formatted in the same way as the query itself.
In the following section we’re going to have a quick look into to GraphQL components.
NOTE
For a deep-dive into what you can do with GraphQL, check out the GraphQL Foundation's introduction here.
Operations
In GraphQL there are two possible operations: queries and mutations.
Query
A query performs the READ operation and does not change or alter any data.
Bellow is an example of a query that retrieves the IDs and names of the items inside a specific board:
query{
boards(ids:1234567){
items{
id
name
}
}
}
Mutation
A mutation is a special type of query that performs the CUD (Create, Update, Delete) operations to modify your data. Mutations return an instance of the object you just modified, so you can query the data you changed.
Below is an example of a create_item()
mutation that will return the ID and the name of the newly created item:
mutation{
create_item(board_id: 1234567, item_name: "New Item"){
id
name
}
}
Multiple queries in one request
You can also send multiple queries in one request, which will be executed one after the other:
query {
checkBoard1: boards(ids:1234567){
id
name
}
checkBoard2: boards(ids:2345678){
id
name
}
}
mutation{
createItem1: create_item(board_id: 1234567, item_name:"This is a new Item 1") {
id
name
}
createItem2: create_item(board_id: 1234567, item_name:"This is a new Item 2") {
id
name
}
}
Object Types
Object types are a collection of fields, which are used to describe the set of possible data you can query using the API.
Fields
Fields specify certain properties of objects.
Each object contains fields that can be queried by name to retrieve specific properties of the object.
query {
boards {
id
}
}
Arguments
You can pass arguments in a query to determine the returned data (i.e. filtering the search results) and to narrow down the results to only the specific ones you’re after.
In the following example, the object is “boards”, the requested field is “title”, the argument is “ids”, and the argument value is 157244624.
query {
boards (ids: 1234567){
title
}
}
GraphQL Visual Interface (GraphiQL)
One of the most powerful parts of GraphQL is its visual interface. GraphiQL is an in-browser tool for writing, validating, and testing GraphQL queries.
Before diving in and querying the API, it’s highly recommended for you to run your queries through this visual interface. This will allow you to ensure that your queries are correct, and the data being returned is expected.
GraphiQL is available in the Playground here.
Variables
Variables can be used to pass dynamic values to your arguments. Variables are written outside of the query string itself, in the variables section, and passed to the arguments.
When we start working with variables, we need to do three things:
- Replace the static value in the query with
$variableName
- Declare
$variableName
as one of the variables accepted by the query - Pass
variableName: value
in the separate, transport-specific (usually JSON) variables dictionary
mutation change_column_value($value: JSON!) {
change_column_value (board_id: 157244624,item_id: 9539475, column_id: "status", value: $value) {
id
}
}
query variables:
{
"value": "{\"index\": 1}"
}
monday.com schema
Our GraphQL schema defines the structure of the available API data and contains all of the possible queries and mutations you can use. It is a valuable resource that you can use to verify your API responses and extract useful information from the metadata.
We expose our schema here.
Do you have questions?
Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.
Don’t forget to search before opening a new topic!
Updated 4 months ago