Este artículo te explicará cómo usar la API GraphQL de monday.com con Python. Empezaremos con lo más básico y luego seguiremos con consultas más complicadas. Tómate tu tiempo para revisarlo a tu modo. 

 

¿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, 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 Python en funcionamiento en tu equipo
• Una cuenta activa de monday.com (regístrate aquí si aún no lo has hecho)
• Entendimiento básico de las API web y las solicitudes HTTP
• Entendimiento básico de Python

 

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 por obtener una lista de los tableros junto con sus nombres y los ID del tablero. Para ello, especificaremos "tableros" en nuestra búsqueda y luego especificaremos

Ejecuta el siguiente código en tu entorno Python:

import requests
import json

apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}

query = '{ boards (limit:5) {name id} }'
data = {'query' : query}

r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())

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 diccionario 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 Python:

import requests
import json

apiKey = "TU_CLAVE_DE_API_AQUI"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}

query2 = '{boards(limit:1) { name id description items_page { items { name column_values{id type text } } } } }'
data = {'query' : query2}

r = requests.post(url=apiUrl, json=data, headers=headers) # enviar la consulta
print(r.json())

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. Observa que estamos usando comillas dobles para el argumento "item_name", para diferenciar la cadena interna de la consulta en sí. 

import requests
import json

apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}

query3 = 'mutation{ create_item (board_id:YOUR_BOARD_ID, item_name:"WHAT IS UP MY FRIENDS!") { id } }'
data = {'query' : query3}

r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())

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:

import requests
import json

apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}

query4 = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName) { id } }'
vars = {'myItemName' : 'Hello everyone!'}
data = {'query' : query4, 'variables' : vars}

r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())

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".

import requests
import json

apiKey = "YOUR_API_KEY_HERE"
apiUrl = "https://api.monday.com/v2"
headers = {"Authorization" : apiKey}

query5 = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName, column_values:$columnVals) { id } }'
vars = {
 'myItemName' : 'Hello everyone!',
 'columnVals' : json.dumps({
   'status' : {'label' : 'Done'},
   'date4' : {'date' : '1993-08-27'}
 })
}

data = {'query' : query5, 'variables' : vars}
r = requests.post(url=apiUrl, json=data, headers=headers) # make request
print(r.json())

¡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.