Cómo crear una API REST con una custom query y procesado
Introducción
En este tutorial se va a explicar cómo crear una operación personalizada (custom query) en una API REST, incluyendo parámetros y procesando la respuesta.
Para este tutorial se hará uso del entorno de CloubLab (https://lab.onesaitplatform.com) y la Entidad de «HelsinkiPopulation».
Pasos
Crear una API REST
Se accederá al listado de API REST a través del menú de Procesamiento > APIs.
Se mostrará entonces el listado con las APIs a las que tiene acceso el usuario, ya sean propias como compartidas por otros usuarios (las que se muestran como públicas).
Para crear la nueva API, se pulsará en el botón de «+» situado en la parte superior derecha de la pantalla.
Esto abrirá el asistente de creación de la API, en donde se tendrá que introducir una información básica:
Habrá que introducir la siguiente información:
Identificación: el nombre único con el que identificar a la API.
Versión: la versión actual de la API. Este valor es autogenerado.
Categoría: para definir la API y poder filtrarlo fácilmente a la hora de buscarlo.
Tipo de API REST: representa el tipo de API a crear. En este caso se seleccionará la opción de «Publicar Entidad como API REST».
Entidad: se seleccionará la Entidad de «HelsinkiPopulation»:
Meta-Información: etiquetas con las que caracterizar la API REST, que servirán para su filtrado a la hora de hacer búsquedas.
EndPoint base: campo autogenerado con la URL de la API REST a crear.
EndPoint Swagger: la URL del Swagger de la API REST.
Descripción: texto descriptivo extendido de la API REST, como su uso, propiedades, características, etc.
El resto de propiedades se dejarán vacías, y tampoco se generarán operaciones básicas en la API REST.
Consulta personalizada
En la parte superior derecha se pulsará sobre el botón de «+ Query Custom»:
Se abrirá entonces un modal en el que preparar la consulta personalizada:
En dicha pantalla se tendrá que indicar la siguiente información:
Método: se elegirá la opción de
GET.Nombre: el nombre del método con el que se invocará la consulta personalizada. En este ejemplo, se podría poner como nombre
getPopulationByYear.Consulta: como consulta a la Entidad, se quiere recuperar la población para un año determinado. Para ello, se utilizará para siguiente consulta:
SELECT c.Helsinki
FROM HelsinkiPopulation AS c
WHERE c.Helsinki.year = {$year}En este caso, {$year} es un parámetro al que se le podrá pasar uno u otro valor a la hora de hacer la consulta. Para probar el funcionamiento, cambiar el valor por el número 1875 y comprobrar que, efectivamente, devuelve un resultado.
Tipo de consulta: como la consulta está en SQL, se mantendrá como está.
Descripción: texto descriptivo extendido del método, explicando lo que hace.
Tras añadir el parámetro, se actualizará la sección de «Parámetros Query», mostrando el parámetro creado («year» en este caso) y teniendo que configurar dos opciones:
Tipo: el tipo del parámetro; en este caso será un tipo número.
Localización: dónde se definirá el parámetro en la llamada; se usará el encabezado.
Una vez terminada de definir la consulta personalizada, se podrá guardar pulsando en el botón de «Guardar cambios».
La consulta personalizada aparecerá entonces en el listado de operaciones:
Para terminar de crear la API REST, se pulsará en el botón de «Guardar cambios» situado en la parte superior derecha de la pantalla.
Invocar la API REST
Para comprobar el funcionamiento real de la operación personalizada, se lanzará desde el Swagger disponible en la API REST.
En primer lugar, será necesario obtener el token de acceso, del cual existen dos tipos:
X-OP-APIKey: este es un token personalizado para cada usuario, el cual es más sencillo para invocar una API desde dentro de la Plataforma.
OAuth2: este token se genera automáticamente por la Plataforma dentro del ciclo de vida OAuth2. Este es el método recomendado cuando se invoca la API REST desde fuera de la Plataforma.
Para consultar el OAuth2, así como visualizar los tokens de X-OP-APIKey, desde el mismo menú de antes se seleccionará la opción de APIs:
Se mostrará entonces un modal con el token de OAuth2 y los tokens X-OP-APIKey disponibles para el usuario:
Una vez que se conoce dónde se encuentran los tokens, desde en listado de APIs REST, se buscará la API REST recién creada, y en sus opciones se seleccionará la opción de «Swagger».
Las APIS de Onesait Platform se publican siguiendo el estándar Open API 3. Dentro del Control Panel se integra el UI de Swagger para poder invocar a estas APIs.
Se mostrará entonces una vista de Swagger con la operación personalizada creada previamente:
Lo primero que habrá que hacer es autorizar el Swagger. Para ello, se pulsará en el botón de «Authorize», lo que mostrará un modal en el que añadir el valor de X-OP-APIKey u OAuth2:
Tras introducir el tipo de token que se desee, se pulsará en el botón de «Authorize» para almacenar el token y autorizar las operaciones.
Hecho esto, únicamente habrá que escoger la operación personalizada, pulsar en el botón de «Try it out», añadir como parámetro un año (1875, por ejemplo) y lanzar la operación con el botón de «Execute»:
Procesar la respuesta de la consulta personalizada
Tal como funciona ahora mismo la consulta, se devuelve un listado con todos los campos de aquellas instancias cuyos años correspondan con el indicado en el parámetro de año que se le indique.
En casos concretos donde se tenga que adaptar la respuesta, es posible modificar la respuesta mediante un procesado de la misma.
Para ello, se editará la API desde el listado de APIs disponibles pulsando en el botón de «✎» (editar).
Se irá hasta la operación personalizada que se ha creado, y se pulsará en el botón de «✎» (editar).
En la parte inferior, se marcará la casilla de «Activar procesado», lo que habilitará una ventana en la que poder procesar la respuesta de la consulta usando JavaScript, en donde la variable «data» sería la respuesta de la consulta:
Se modificará el código para que la respuesta sea únicamente el año y la población, eliminando el elemento raíz:
// data is a string variable containing the query output
var dataArray = JSON.parse(data);
var arrayWithOnlyGeneralPopulation = {
"year": dataArray[0].Helsinki.year,
"population": dataArray[0].Helsinki.population
}
// A string result must be returned
return (JSON.stringify(arrayWithOnlyGeneralPopulation));Guardando los cambios, y actualizando la vista de Swagger, lanzando de nuevo la operación se obtendrá la nueva respuesta: