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 da 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 PHP funcional
• Uma conta ativa na monday.com (inscreva-se em monday.com se ainda não tiver)
• Uma compreensão básica de APIs web e requisições HTTP
• Uma compreensão básica de PHP

Estruturando suas solicitações de API

Há algumas coisas a ter em mente ao construir sua primeira chamada de API:

• Estrutura da Solicitação: todas as solicitações para a API devem ser solicitações POST. As consultas devem estar em conformidade 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. Aprenda 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 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 dos quadros. Para fazer isso, especificaremos o objeto “boards” em nossa consulta e, em seguida, executaremos o seguinte script em seu servidor PHP: 

<?php
$token = 'SEU_TOKEN_AQUI';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = '{ boards { id name } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
  'method' => 'POST',
  'header' => $headers,
  'content' => json_encode(['query' => $query]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

Navegue até a URL do seu servidor em seu navegador. Você deve ver 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 array e fazer o que quiser com eles. Percorra-os; construa uma árvore; divirta-se.

Obtendo dados de itens específicos

Agora vamos aproveitar a flexibilidade do GraphQL e retornar o nome do item e suas colunas, bem como o tipo, título e ID de cada coluna.

Aqui está nossa consulta:

{ items (ids: [1234567890, 9876543210, 1122334455]) {
    name
    column_values {
      column {
        title
        id
        type
      } 
    } 
  } 
}

Seguindo o exemplo anterior, execute isso em seu servidor PHP:

<?php
$token = 'SEU_TOKEN_AQUI';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = '{items(ids:[1234567890, 9876543210, 1122334455]) { name column_values { column { title id text } } } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => $headers,
    'content' => json_encode(['query' => $query]),
  ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

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: SEU_BOARD_ID_AQUI, item_name: "OLÁ MEUS AMIGOS!") {
  id
} }

E aqui está o código para fazer essa solicitação. Observe que estamos usando aspas duplas para o argumento “item_name”, para diferenciar a string interna da própria consulta.

<?php
$token = 'SEU_TOKEN_AQUI';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = 'mutation{ create_item (board_id:SEU_BOARD_ID, item_name:"OLÁ MEUS AMIGOS!") { id } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

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 cortar e colar 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 solicitação de API.

Veja como isso funciona na prática:

<?php
$token = 'SEU_TOKEN_AQUI';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = 'mutation ($myItemName: String!) { create_item (board_id:SEU_BOARD_ID, item_name:$myItemName) { id } }';
$vars = ['myItemName' => 'Olá mundo!'];

$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query, 'variables' => $vars]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

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 template “Começar do zero”.

<?php
$query = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:SEU_BOARD_ID, item_name:$myItemName, column_values:$columnVals) { id } }';
$vars = ['myItemName' => 'Olá mundo!', 
  'columnVals' => json_encode([
    'status' => ['label' => 'Concluído'], 
    'date4' => ['date' => '1993-08-27']
])];

$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query, 'variables' => $vars]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

Parabéns! Você completou este tutorial.

Dê um presente a si mesmo!

Você merece. 🔮​ 

Ainda precisa de assistência? Acesse o suporte da monday.com.

Sabia que a Audatia é parceira oficial da monday.com no Brasil? Ajudamos times a extrair o máximo da ferramenta com consultoria especializada e treinamentos focados na sua operação. Conheça nossos serviços →