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:

1. Replace the static value in the query with $variableName
2. Declare $variableName as one of the variables accepted by the query
3. 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!