Este artigo irá guiá-lo através de algumas operações básicas usando a API GraphQL da monday.com e, em seguida, avançar para consultas mais complicadas. Você pode passar por ele tão rápido ou devagar quanto desejar. Você pode baixar todo o código de exemplo aqui.
O que é a API da monday.com?
A API da monday.com permite que aplicativos externos recuperem e editem dados do Work OS da monday.com.
Por exemplo, você pode usar a API para sincronizar dados entre a monday.com e outra plataforma, de modo que as ações de sua equipe na monday.com sejam sincronizadas com as outras ferramentas que você utiliza.
A API da monday.com é construída sobre GraphQL, que é um pouco diferente das APIs REST que você pode estar acostumado. O esquema GraphQL define objetos e campos que podem ser consultados através da nossa API.
Tópicos abordados
- O que é GraphQL e por que é útil
- Como estruturar uma solicitação para a API da monday.com
- Como escrever consultas simples
- Como escrever mutações para alterar dados na monday.com
Pré-requisitos
- Um ambiente Javascript funcional em seu computador
- Uma conta ativa na monday.com (inscreva-se em monday.com se ainda não tiver)
- Um entendimento básico de APIs web e requisições HTTP
- Um entendimento básico de Javascript
Estruturando suas requisições de API
Há algumas coisas a ter em mente ao construir sua primeira chamada de API:
- Estrutura da Requisição: todas as requisições para a API devem ser requisições POST. As consultas devem estar em conformidade com nosso esquema GraphQL
- Autenticação: todas as requisições para a API devem incluir um token de autenticação no cabeçalho da requisição. Aprenda como obter sua chave de API aqui.
- Corpo da Requisição: todas as requisições para a API devem ter um corpo formatado em JSON. A única exceção são os uploads de arquivos, que devem ser requisições multipart.
Fazendo sua primeira chamada de API
A API da monday.com pode recuperar objetos e seus campos associados do Work OS.
Vamos começar recuperando uma lista de quadros, juntamente com seus nomes e IDs de quadro. Para fazer isso, especificaremos o objeto “boards” em nossa consulta e, em seguida, especificaremos o número de resultados que gostaríamos de retornar, juntamente com o nome e o ID do quadro.
Cole o seguinte código em seu ambiente Javascript:
let query = '{ boards (limit:5) {name id} }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Você deve receber uma resposta que contém uma lista de quadros, assim:
Observe que os dados retornados estão em JSON, então você pode serializá-los em um objeto Javascript e fazer o que quiser com eles. Percorra-os; construa uma árvore; divirta-se.
Obtendo todos os dados de um quadro
Agora vamos aproveitar a flexibilidade do GraphQL e retornar um conjunto mais completo de dados para um determinado quadro. Especificamente, retornaremos o nome, ID e descrição do quadro e, em seguida, todos os itens no quadro. Para cada item, retornaremos o valor e o tipo de cada coluna.
Aqui está nossa consulta:
{ boards (limit:1) {
name
id
description
items_page {
items {
name
column_values {
id
type
text
} } } } }
Seguindo o exemplo anterior, cole isso em seu ambiente Javascript:
let query = '{boards(limit:1) { name id description items_page { items { name column_values{id type text } } } } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Você receberá um conjunto de dados muito mais rico com esta consulta.
Criando um novo item
Nesta seção, escreveremos uma mutação para criar um novo item em seu quadro.
As mutações são operações que adicionam ou atualizam dados e também retornam campos do objeto que foi criado ou alterado. Os dados que você está alterando são passados como argumentos para a mutação.
Aqui está a consulta que usaremos:
mutation {
create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "O QUE HÁ MEUS AMIGOS!") {
id
} }
E aqui está o código para fazer essa requisição. Observe que estamos adicionando um \ (caractere de escape) na frente de cada aspas no argumento “item_name”, para diferenciar a string interna da própria consulta.
let query3 = 'mutation{ create_item (board_id:YOUR_BOARD_ID_HERE, item_name:\"O QUE HÁ MEUS AMIGOS!\") { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query3
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Quando a mutação for bem-sucedida, você receberá uma resposta que contém o ID do item que acabou de criar:
Criando um novo item usando variáveis GraphQL
Até agora, temos escrito consultas e mutações com valores codificados. Ou seja, se eu quisesse mudar o quadro no qual estou criando um item, teria que modificar a string da consulta, o que pode ser custoso.
No entanto, podemos preencher dinamicamente argumentos em nossa consulta usando variáveis GraphQL. Passamos as variáveis como um objeto JSON, e o GraphQL irá inserir dinamicamente as variáveis em nossa consulta!
Precisamos declarar o tipo das variáveis em nossa consulta e passar as variáveis como um objeto JSON separado dentro de nossa requisição de API.
Veja como isso funciona na prática:
let query4 = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID_HERE, item_name:$myItemName) { id } }';
let vars = {"myItemName" : "Olá, mundo!"};
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query4,
'variables' : JSON.stringify(vars);
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Como antes, uma mutação bem-sucedida retornará o ID do item que você criou.
Criando um novo item com valores de coluna preenchidos
No nosso exemplo final, criaremos um novo item e definiremos os valores para cada uma de suas colunas.
Nosso esquema GraphQL define um conjunto de valores de coluna como uma string JSON (pares chave-valor). As chaves do objeto column_values devem ser IDs de coluna, e os valores devem ser estruturados dependendo do tipo da coluna.
Este exemplo específico atualiza uma coluna de status e uma coluna de data. Você pode configurar um quadro para este exemplo usando nosso modelo “Começar do zero”.
let query5 = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID_HERE, item_name:$myItemName, column_values:$columnVals) { id } }';
let vars = {
"myItemName" : "Olá, mundo!",
"columnVals" : JSON.stringify({
"status" : {"label" : "Concluído"},
"date4" : {"date" : "1993-08-27"}
})
};
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query5,
'variables' : JSON.stringify(vars)
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Parabéns! Você completou este tutorial.
Presenteie-se!
Você merece. 🔮
Ainda tem dúvidas? Entre em contato com o suporte oficial da monday.com.
Quer implementar a monday.com com mais eficiência na sua empresa? A Audatia é parceira oficial da monday.com no Brasil e oferece serviços de consultoria, treinamento e otimização de processos. Entre em contato →
