Este artículo te explicará cómo realizar algunas operaciones básicas con la API GraphQL de monday.com y, luego, cómo realizar consultas más complicadas. Tómate tu tiempo para revisarlo a tu modo. Puedes descargar todo el código de muestra aquí. 

 

¿Qué es la API de monday.com?

Con la API de monday.com, las aplicaciones externas pueden recuperar y editar datos del sistema operativo de trabajo monday.com.

Por ejemplo, puedes usar la API para sincronizar datos entre monday.com y otra plataforma, para que las acciones del equipo en monday.com estén sincronizadas con las otras herramientas que usas.

Nuestra API se basa en GraphQL, que es un poco diferente de las API REST a las que probablemente ya conozcas. Nuestro esquema GraphQL define objetos y campos que se pueden consultar a través de nuestra API.

 

Temas que trataremos

• Qué es GraphQL y por qué es útil
• Cómo estructurar una solicitud a la API de monday.com
• Cómo escribir consultas sencillas
• Cómo escribir mutaciones para cambiar los datos en monday.com

 

Requisitos previos

• Un entorno de Javascript en funcionamiento en tu equipo
• Una cuenta activa de monday.com (regístrate en monday.com si aún no lo has hecho)
• Entendimiento básico de las API web y las solicitudes HTTP
• Entendimiento básico de Javascript

 

Estructurar las solicitudes de API

Hay algunas cosas que debes tener en cuenta al crear tu primera solicitud de API:

• Estructura de la solicitud: todas las solicitudes a la API deben ser solicitudes POST. Las solicitudes deben ajustarse a nuestro esquema de GraphQL
• Autenticación: todas las solicitudes a la API deben incluir un token de autenticación en el encabezado de la solicitud. Aprende a cómo obtener tu clave de API aquí. 
• Cuerpo de la solicitud: todas las solicitudes a la API deben tener un cuerpo con formato JSON. La única excepción son las cargas de archivos, que deben ser solicitudes multiparte.

 

Realiza tu primera solicitud a la API

La API de monday.com puede recibir objetos y sus campos asociados del sistema operativo de trabajo (Work OS).

Comencemos recuperando una lista de tableros, junto con sus nombres e IDs de tablero. Para hacer esto, especificaremos el objeto "tableros" en nuestra solicitud y luego especificaremos la cantidad de resultados que nos gustaría devolver junto con el nombre del tablero y el ID del tablero.

Pega el siguiente código en tu entorno 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)));

Deberás recibir una respuesta que contenga una lista de tableros, de esta forma:

Ten en cuenta que los datos recibidos son JSON, por lo que puedes serializarlos en un objeto Javascript y hacer lo que quieras con ellos. Itera a través del texto, construye un gráfico de árbol, ¡lo que se te ocurra!

 

Obtén todos los datos de un tablero

Ahora, aprovechemos la flexibilidad de PostgreSQL y devolvamos un conjunto completo de datos para un tablero determinado. Específicamente, devolveremos el nombre, Id. y descripción del tablero y, luego, todos los elementos del tablero. Para cada elemento, devolveremos el valor y el tipo de cada columna.

Esta es nuestra consulta:

{ 
  boards (limit:1) {
  name
  id
  description
  items_page {
    items {
    name
    column_values {
      id
      type
      text
} } } } }

 

Siguiendo lo mismo del ejemplo anterior, pégalo en tu entorno de 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)));

Recibirás un conjunto de datos mucho más completo con esta consulta.

 

Crear un elemento nuevo

En esta sección, escribiremos una mutación para crear un elemento nuevo en tu tablero.

Las mutaciones son operaciones que agregan o actualizan datos, y también devuelven campos en el objeto que se creó o cambió. Los datos que cambias se pasan como argumentos en la mutación.

Aquí puedes ver la consulta que usaremos:

mutation {
  create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {
  id
} }

Y aquí está el código para realizar esta solicitud. Observe que estamos agregando un \ (carácter de barra oblicua invertida) delante de cada comilla en el argumento "item_name", para diferenciar la cadena interna de la consulta en sí.

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)));

Cuando la mutación es exitosa, recibirás una respuesta que contenga el Id. del elemento que acabas de crear:

 

Crear un nuevo elemento usando variables de GraphQL

Hasta ahora, hemos estado escribiendo consultas y mutaciones con valores codificados en ellas. Es decir, si quisiera cambiar el tablero en el que estoy creando un elemento, tendría que reestructurar y editar la cadena de consulta de nuevo, lo cual puede ser costoso.

Sin embargo, podemos rellenar de forma dinámica los argumentos de nuestra consulta utilizando variables de GraphQL. Pasamos las variables como un objeto JSON y ¡GraphQL insertará dinámicamente las variables en nuestra consulta!

Necesitamos declarar el tipo de variables en nuestra consulta y pasar las variables como un objeto JSON separado dentro de la solicitud API.

Así es como se ve en acción:

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)));

Igual que antes, una mutación exitosa devolverá el Id. del elemento que creaste.

 

Crear un elemento nuevo con valores de columna completados

En nuestro ejemplo final, crearemos un nuevo elemento y definiremos los valores para cada una de sus columnas.

Nuestro esquema de GraphQL define un conjunto de valores de columna como una cadena JSON (pares clave-valor). Las claves del objeto column_values deben ser Id. de columnas y los valores deben estar estructurados según el tipo de columna.

Este ejemplo en particular actualiza una columna Estado y Fecha. Puedes configurar un tablero para este ejemplo, usando nuestra plantilla para "Empezar desde cero".

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)));

¡Felicitaciones! Has completado este tutorial.

 

¡Tómate un descanso!

Te lo mereces. 🔮​ 

 

 

Si tienes preguntas, comunícate con nuestro equipo aquí. Estamos disponibles las 24 horas, los 7 días de la semana, y será un gusto ayudarte.