Probando API's GraphQL con Postman

¿Qué es GraphQL?

GraphQL es un lenguaje de consulta y un entorno de ejecución para APIs que fue desarrollado por Facebook en 2012 y posteriormente se hizo público en 2015. Es una tecnología moderna y flexible que permite a los clientes obtener datos precisos y personalizados de un servidor de manera eficiente.

La estructura de una consulta en GraphQL se define mediante un esquema, que actúa como un contrato entre el cliente y el servidor. El esquema describe los tipos de datos disponibles, los campos que pueden ser consultados y las relaciones entre ellos.

Algunas diferencias entre GraphQL y API REST

Características:

Entendiendo GraphQL

A diferencia de las API REST, donde múltiples endpoints definen las operaciones disponibles, GraphQL se basa en un único endpoint y permite a los clientes solicitar exactamente los datos que necesitan. Por lo que cuenta con 3 operaciones principales que son: Queries, mutaciones y subscripciones, comprender como utilizar estas operaciones, nos facilitará el proceso de pruebas. Vamos a centrarnos en Mutaciones y Queries.

Conceptos que deberás tener en cuenta al momento de probar API GraphQL

Overfetching

El overfetching ocurre cuando una consulta (query) solicita más datos de los que realmente necesita el cliente. Es decir, el servidor entrega información adicional más allá de lo que el cliente requiere en su solicitud específica. Con GraphQL se busca solucionar esto, que suele ser común en API REST

Ejemplo: El cliente necesita obtener solo el nombre y el correo de usuario. Sin embargo el servidor devuelve la información completa del usuario, incluyendo el número de teléfono, el apellido y la fecha de cumpleaños.

Underfetching

El underfetching ocurre cuando una consulta (query) no obtiene suficientes datos para satisfacer todas las necesidades de la interfaz de usuario en una sola llamada al servidor. Es decir, el cliente necesita realizar múltiples solicitudes para obtener la información completa que requiere, lo que puede llevar a una ineficiencia en el rendimiento y a una mayor complejidad en la lógica del cliente. Con GraphQL se busca solucionar esto, que suele ser común en API REST

Ejemplo: El cliente necesita obtener el nombre y el correo de usuario. La consulta solo devuelve el correo del usuario.

Peticiones POST en GraphQL

A diferencia de API REST donde se utilizan diferentes métodos para hacer las peticiones (GET, POST, PUT) ; en GraphQL se realizan a través del método HTTP POST, es decir concentra todas las operaciones en un único punto de entrada, POST.

Respuestas en GraphQL

Por convención, GraphQL siempre retornará un código de estado HTTP 200 OK en sus respuestas. Esto significa que la solicitud fue procesada y es servidor puede retornar data o errors en su respuesta.

*Data: Corresponde a los datos solicitados

*Errors: Corresponde a errores, por ejemplo de validación de campos, no se encontró el recurso, etc.

Cuando ocurra un error no controlado dentro del servidor (ejemplo: no se esta controlando si la conexión a BD falla) el servicio retornará un código de estado HTTP 500

Iniciando con pruebas en GraphQL utilizando Postman

Crear un colección utilizando GraphQL

Una vez configurado correctamente el proyecto con el endpoint a probar ya sea local o remotamente, podemos iniciar con Postman

1. Crear un cuenta en Postman(es gratis) y luego crear una nueva colección en My Workspace>>New>> (para el ejemplo vamos a elegir GrapnQL; es valido aclarar que también es posible probar usando HTTP).

2. Ingresar la url del servidor, en mi caso estoy utilizando el local. Una vez ingresada, ve a la pestaña Schema donde podrás importar el esquema para facilitar las pruebas. Este debe estar disponible la raíz del proyecto en la carpeta graphql-schema/schema.graphql o bien usar la opción Use GraphQL Introspection para importarlo del endpoint previamente ingresado en la URL

Una vez importado y sí todo salió bien, en la pestaña Query se deberá mostrar la lista de Queries y Mutaciones disponibles. Todo listo para iniciar la prueba

Prueba básica de Mutaciones

Vamos a probar una mutación, el primer paso será escribirla, pero como tenemos el esquema importado, únicamente debemos darle clic sobre la casilla de verificación de la mutación que queremos probar, esto mostrará automáticamente en la parte derecha, los parámetros que va a devolver la mutación. Estos pueden ser modificados de acuerdo a los criterios de aceptación que se están probando.

Ahora es necesario ingresar los inputs para poder crear el usuario, se pueden ingresar manualmente o bien con el asistente, dando clic para desplegar el árbol de input e ingresar los datos con los que se va a crear el usuario. Recuerda que los campos marcados con ! al final, son requeridos.

Una vez la información se va ingresando esta se muestra a la derecha, como en la siguiente imagen

En este momento ya esta listo la mutación para ser enviada, si todos los datos son correctos esto creará un registro en la BD y en la respuesta mostrará el nombre, apellido, celular, email:

Prueba utilizando variables

Sabemos que este tipo de pruebas las vamos a usar más de un una vez durante la revisión del endpoint, y seguramente mas adelante vamos a automatizar. Pero para repetir esta prueba una y otra vez y evaluar los diferentes criterios de aceptación, vamos a necesitar datos diferentes que quizá es mejor generarlos que manera aleatoria en lugar de escribirlos una y otra vez. Entonces vamos a empezar definiendo las variables con los parámetros necesarios para crear el usuario.

En la sección variables, vamos a colocar todos los nombres de los inputs requeridos para crear el usuario, de la siguiente manera.

El nombre incluido en el objeto data debe ser del tipo especifico requerido en la mutación/consulta. Ejemplo: En la siguiente imagen se muestra una variable data que es de tipo UserCreateInput! la cual debe contener los datos requeridos por este.

Y ahora vamos a modificar la mutación para que utilice la variable que acabamos de definir, por lo que quedará de la siguiente manera

Para utilizar la variable, debemos anteponer el signo $ seguido del nombre de la variable y definiendo un tipo. El nombre de la variable puede ser cualquier nombre, pero que sea fácil de entender e identificar.

Asignando valores dinámicos a las variables

Ahora bien, para este caso, el email y el número de celular deben ser únicos, así que lo mejor es asignar valores dinámicos.

1. Se deberán definir los scripts que harán que los valores sean variables, esto debemos hacerlo para cada uno de los parámetros de la siguiente manera: En la pestaña Scripts, opción Before, definir una función para cada parámetro que queremos sea variable; de esta manera tendremos valores aleatorios cada vez que se ejecute la prueba.

Nota: Si estas utilizando la opción de pruebas de HTTP, estos scripts deberán estar en la pestaña de Pre-Request-Script

Ahora en la variables, vamos a reemplazar los valores fijos por las variables seteadas en el Before

De esta manera cada vez que se ejecute este test vamos a tener siempre valores diferentes.

Test Básicos

Desde la opción GraphQL podemos hacer algunos test básicos, como validar tiempos de respuesta, si la respuesta es correcta, o si la respuesta cumple con alguna condición especifica.

Otras herramientas para probar GraphQL

Además de Postman, tenemos a disposición varias herramientas que nos permiten realizar pruebas y explorar APIs GraphQL. Lo que facilita facilitar la interacción con servidores GraphQL, permitiendo a los desarrolladores realizar consultas, ejecutar mutaciones y verificar respuestas sin problemas.

A continuación algunas alternativas muy intuitivas que te ayudaran a entrar en este mundo de explorar y testear API GraphQL.