Este artigo orientará você a realizar algumas operações básicas usando a API GraphQL da monday.com e, em seguida, apresentará consultas mais complicadas. Leia este artigo de acordo com a sua necessidade. Você pode baixar todo o código de amostra aqui. 

 

Qual é a API da monday.com?

A API da monday.com permite que aplicativos externos recuperem e editem dados da Work OS da monday.com.

Por exemplo, você pode usar a API para sincronizar dados entre a monday.com e outra plataforma, para que as ações da sua equipe na monday.com sejam sincronizadas com as outras ferramentas que você usa.

Nossa API é baseada no GraphQL, que é um pouco diferente das APIs REST mais comuns. Nosso esquema GraphQL define objetos e campos que podem ser consultados por meio de nossa API.

 

Tópicos abordados

• O que é o GraphQL e por que ele é útil
• Como estruturar uma solicitação para a API monday.com
• Como escrever consultas simples
• Como escrever mutações para alterar dados na monday.com

 

Pré-requisitos

• Um ambiente Javascript em funcionamento no seu computador
• Uma conta ativa da monday.com (registre-se na monday.com se ainda não o fez)
• Um entendimento básico de APIs da web e solicitações HTTP
• Um entendimento básico de Javascript

 

Estruturando suas solicitações de API

Há algumas coisas a ter em mente quando você está construindo sua primeira chamada de API:

• Estrutura de solicitações: todas as solicitações para a API devem ser solicitações POST. As consultas devem estar de acordo com nosso esquema GraphQL
• Autenticação: todas as solicitações para a API devem incluir um token de autenticação no cabeçalho da solicitação. Saiba como obter sua chave de API aqui. 
• Corpo da solicitação: todas as solicitações para a API devem ter um corpo formatado em JSON. A única exceção são os uploads de arquivos, que devem ser solicitações de várias partes.

 

Fazer a primeira chamada de API

A API monday.com pode recuperar objetos e seus campos associados ao Work OS (sistema operacional de trabalho).

Vamos começar recuperando uma lista de quadros, junto com seus nomes e IDs de quadro. Para isso, especificaremos o objeto "quadros" na nossa consulta e, em seguida, o número de resultados que queremos obter, juntamente com o nome e o ID do quadro.

Cole o seguinte código no 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, conforme abaixo:

Observe que os dados retornados são JSON, então você pode serializá-los em um objeto Javascript e fazer o que quiser com ele. Divirta-se!

 

Obter 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, devolveremos o nome, a ID e a descrição do quadro e, em seguida, todos os elementos do quadro. Para cada elemento, retornaremos o valor e o tipo de cada coluna. Para cada elemento, 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-o 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 essa consulta.

 

Criar um novo elemento.

Nesta seção, escreveremos uma mutação para criar um novo elemento no seu quadro.

Mutações são operações que adicionam ou atualizam dados e também retornam campos no 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: "WHAT IS UP MY FRIENDS!") {
  id
} }

E aqui está o código para fazer essa solicitação. Observe que estamos adicionando um \ (caractere de escape) na frente de cada aspas no argumento "item_name" para diferenciar a cadeia de caracteres interna da própria consulta.

let query3 = 'mutation{ create_item (board_id:YOUR_BOARD_ID_HERE, item_name:\"WHAT IS UP MY FRIENDS!\") { 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 a ID do elemento que acabou de criar:

 

Criando um novo elemento usando variáveis do GraphQL

Até agora, escrevemos consultas e mutações com valores codificados nelas. Ou seja, se eu quisesse mudar o quadro em que estou criando um elemento, teria que deslizar e dividir a cadeia de caracteres de consulta, o que pode ser caro.

No entanto, podemos preencher argumentos dinamicamente em nossa consulta usando variáveis do GraphQL. Passamos as variáveis como um objeto JSON, e o GraphQL 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 solicitação de API.

É assim que se parece em ação:

let query4 = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID_HERE, item_name:$myItemName) { id } }';
let vars = {"myItemName" : "Hello, world!"};

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á a ID do elemento que você criou.

 

Criando um novo elemento com valores de coluna preenchidos

Em nosso exemplo final, criaremos um novo elemento e definiremos os valores para cada uma das suas colunas.

Nosso esquema GraphQL define um conjunto de valores de coluna como uma cadeia de caracteres 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 de data. Você pode configurar um quadro para este exemplo usando nosso template "Start from scratch" ("Começando 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" : "Hello, world!",
  "columnVals" : JSON.stringify({
    "status" : {"label" : "Done"},
    "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ê concluiu este tutorial.

 

Comemore!

Você merece. 🔮​ 

 

 

Se você tiver alguma dúvida, entre em contato com nossa equipe por aqui. Estamos disponíveis 24 horas e prontos para ajudar!