El siguiente artículo tiene como objetivo mostrar cómo crear y publicar una API GraphQL en WSO2 API Manager 3.1.0
¿Qué es GraphQL?
GraphQL son las siglas de Graph Query Language, es un lenguaje de consulta similar a SQL desarrollado por Facebook en 2012, que incluye un entorno de tiempo de ejecución y un sistema de tipos.
GraphQL es una forma alternativa a una interfaz REST para crear una interfaz de un servicio basado en la comunicación utilizando los protocolos web HTTP y JSON como formato de intercambio de datos. Tiene varias ventajas sobre REST al poder realizar varias consultas en una misma petición y devolviendo únicamente los datos que requiera el cliente.
Al igual que como ocurría en la definición del payload de un WebService, mediante un esquema xsd, también aquí definiremos un esquema con el diseño de nuestras entidades y mutaciones (operaciones sobre las entidades, por ejemplo altas, bajas…) las cuales serán accesibles desde nuestro GraphQL Server.
El principal objetivo de GraphQL es evitar las múltiples consultas al servidor.
Un servicio GraphQL se crea definiendo tipos y campos en esos tipos, luego proporcionando funciones para cada campo en cada tipo. Por ejemplo, un servicio GraphQL que nos dice quién es el usuario que inició sesión (me) así como el nombre de ese usuario podría verse así:
type Query {
me: User
}
type User {
id: ID
name: String
}
Junto con funciones para cada campo en cada tipo:
function Query_me(request) {
return request.auth.user;
}
function User_name(user) {
return user.getName();
}
Una vez que se está ejecutando un servicio GraphQL, puede recibir consultas GraphQL para validar y ejecutar. Una consulta recibida se verifica primero para asegurarse de que sólo se refiere a los tipos y campos definidos, luego ejecuta las funciones proporcionadas para producir un resultado.
A continuación se muestra un ejemplo de consulta:
{
me {
name
}
}
El resultado de la consulta quedaría de la siguiente forma:
{
"me": {
"name": "Luke Skywalker"
}
}
Para conocer un poco más de GraphQL y revisar algunos ejemplos puedes visitar el siguiente enlace
Integración de una API GraphQL con WSO2 API Manager 3.1.0
Actualmente se puede usar un esquema de Lenguaje de Definición de Esquema (SDL) para diseñar una API GraphQL en WSO2 API Manager similar a crear una API SOAP usando WSDL y desarrollar una API REST usando Especificaciones OpenAPI (también conocidas como Definiciones Swagger).
En el siguiente ejemplo se mostrará como crear y publicar una API GraphQL en WSO2 API Manager 3.1.0
Prerrequisitos
- Java 1.8 o superior
- WSO2 API Manager 3.1.0
Pasos a seguir para crear y publicar una API GraphQL en WSO2 APIM 3.1.0
1. Para este ejemplo se utilizará el siguiente archivo StarWarsAPI el cual te lo puedes descargar desde aquí, este archivo contiene la definición del esquema de la saga de películas de Star Wars y nos servirá para realizar consultas específicas, por ejemplo obtener todos los títulos de las películas, número de episodio, personajes, planetas, especies, vehículos – naves, etc.
2. Descargar WSO2 API Manager 3.1.0 mediante el siguiente enlace
3. Una vez descargado el producto, debemos descomprimir el archivo wso2am-3.1.0.zip, posteriormente para iniciar el servicio de WSO2 API Manager debemos dirigirnos a la siguiente ruta <WSO2APIM_HOME>\bin y ejecutar el siguiente comando:
En Linux/Mac: sh wso2server.sh start En Windows: wso2server.bat --run
4. Una vez iniciado nuestro servicio, ingresaremos al portal de API Manager Publisher mediante la siguiente url:
https://<hostname>:9443/publisher
Recordar que se debe reemplazar el hostname por la IP del servidor en el que está instalado WSO2 API Manager o simplemente indicar como localhost si lo estás ejecutando desde tu ordenador, quedando de la siguiente forma:
https://localhost:9443/publisher
NOTA: Por default el producto tiene asignado el valor de localhost como hostname, si requieres cambiar dicho valor te dejo el siguiente enlace con las instrucciones correspondientes.
5. Ingresar con las credenciales correspondientes, en este caso utilizaremos las que vienen por default admin:admin
NOTA: Si requieres cambiar las credenciales de acceso os dejamos el siguiente enlace con la información correspondiente.
6. Una vez dentro de la consola, para crear nuestra API daremos clic en el botón CREATE NEW API y posteriormente daremos clic en la opción I Have a GraphQL SDL schema para importar el esquema GraphQL.
En la siguiente ventana nos solicitará cargar el archivo con extension .graphql, el cual descargamos en el punto 1, para eso damos clic en el botón BROWSE FILE TO UPLOAD y posteriormente seleccionamos el archivo schema_graphql.graphql
NOTA: La extensión del archivo puede ser .graphql, .txt o .json.
Una vez que hayamos seleccionado nuestro archivo y lo hayamos cargado, para continuar daremos clic en el botón Next.
7. En la siguiente ventana, para crear la definición de nuestra API, deberemos ingresar el nombre de nuestra API, el contexto, la versión, el endpoint y el business plan, para este ejemplo utilizaremos los siguientes datos:
| Name | StarWarsAPI |
| Context | /swapi |
| Version | 1.0.0 |
| Endpoint | https://api.graph.cool/simple/v1/swapi |
| Business Plans | Unlimited |
Cuando hayamos completado los campos, para finalizar daremos clic en el botón CREATE.
8. En la siguiente ventana nos mostrará que nuestra API ha sido creada.
9. Un dato importante es que podemos revisar la definición de nuestra API que acabamos de crear, esto se puede realizar al dar clic en la opción Schema Definition.
Si se requiriera podemos descargar la definición de nuestra API y realizar las modificaciones correspondientes y posteriormente importarla para actualizar la definición del esquema.
10. Una vez que ha sido creada nuestra API, para continuar con el ejemplo debemos publicarla, para eso daremos clic en el botón PUBLISH.
11. Una vez publicada, requerimos realizar un test de nuestra API, para eso nos dirigiremos a la consola de Dev Portal, por lo que daremos clic en la opción View in Dev Portal.
12. Una vez que fuimos redirigidos a Dev Portal, daremos clic en el botón SIGN-IN para ingresar con nuestro usuario, en este ejemplo utilizamos las credenciales admin:admin
13. Para consumir la API, debemos suscribirnos, para eso damos clic en la opción Subscriptions y posteriormente clic en el botón SUBSCRIBE.
14. Ya estando suscritos a nuestra API, procederemos a generar las Keys de Producción, para eso damos clic en el botón GENERATE KEYS.
15. En la siguiente ventana deberemos copiar el Token que se generó.
16. Ahora es el turno de probar nuestra API, para eso daremos clic en la opción Try Out
En la parte inferior encontrarás el analizador de consultas de GraphQL.
17. Para probar nuestra API, ingresaremos el siguiente ejemplo de payload en el analizador de consultas, lo que queremos obtener es el listado de todas las películas incluyendo su correspondiente título y número de episodio, además de obtener el color de piel de las especies de todos los planetas.
query{
allFilms{
title
episodeId
}
allPlanets{
films{
species{
skinColor
}
}
}
}
18. Una vez ingresado nuestra consulta, daremos clic en el botón Execute.
19. Por último, el resultado se visualizará del lado derecho, la consulta incluye todas las películas con su respectivo título y episodio así como el color de piel de las especies de cada planeta.
Conclusiones
Como se pudo observar, cuando se envía una consulta GraphQL, se obtiene exactamente lo que necesita. Las consultas GraphQL siempre devuelven resultados predecibles. Las aplicaciones que usan GraphQL son rápidas y estables porque controlan los datos que obtienen, no el servidor.
GraphQL es una herramienta que se presenta como una alternativa a REST. La principal mejora que propone es la optimización, además de trasladar la información del servidor al cliente.
