Agrupación de solicitudes de API con NGINX Plus y el módulo JavaScript de NGINX

La versión del módulo JavaScript NGINX lanzada con NGINX Plus R15 ahora puede emitir subsolicitudes, lo que significa que las solicitudes se pueden iniciar en el código JavaScript. Esto permite abordar un conjunto completamente nuevo de casos de uso.

Uno de estos casos de uso es la agrupación de solicitudes de API, de modo que una única solicitud de API de un cliente pueda convertirse en múltiples solicitudes de API a un conjunto de servidores back-end, y las respuestas agregarse en una única respuesta al cliente. En este blog usamos un sitio de comercio electrónico como ejemplo: cuando el cliente solicita información sobre un producto en particular, se realizan subsolicitudes a tres servicios backend: catálogo, inventario y reseñas de clientes.

Esta publicación se basa en el ejemplo de subsolicitud del anuncio de NGINX Plus R15 , que muestra cómo usar subsolicitudes para enviar la misma solicitud a dos servidores back-end y devolver solo la primera respuesta al cliente.

[ Editor : esta publicación es una de varias que exploran casos de uso del módulo JavaScript de NGINX. Para obtener una lista completa, consulte Casos de uso del módulo JavaScript NGINX .

La publicación se actualiza para usar la directiva js_import , que reemplaza la directiva js_include en NGINX Plus R23 y versiones posteriores. Para obtener más información, consulte la documentación de referencia del módulo JavaScript de NGINX : la sección Configuración de ejemplo muestra la sintaxis correcta para la configuración de NGINX y los archivos JavaScript. ]

INTRODUCCIÓN

El objetivo de esta publicación es proporcionar ejemplos prácticos de agrupación de solicitudes de API que sean simples y directos. Los ejemplos cumplen todos los requisitos siguientes:

• El método HTTP GET se utiliza para todas las solicitudes.
• Todas las respuestas están en formato JSON.

• Se admiten dos estilos de solicitudes de API:

  • El argumento del programa API es el elemento final del URI. Lo llamamos estilo de solicitud de elemento final . En nuestro ejemplo, una solicitud de cliente para /batch-api/product/14286 genera solicitudes a /myapi/catalog/14286 , /myapi/inventory/14286 y /myapi/review/14286 .
  • El argumento se identifica en la cadena de consulta del URI. A esto lo llamamos estilo de solicitud de cadena de consulta . En el ejemplo, una solicitud para /batch-api2/product?item=14286 genera solicitudes a /myapi/catalog.php?item=14286 , /myapi/inventory.php?item=14286 y /myapi/review.php?item=14286 .

  Tenga en cuenta que con cualquier estilo puede haber argumentos adicionales en la cadena de consulta.

• El conjunto de subsolicitudes activadas por una solicitud de cliente se puede configurar dinámicamente, lo que significa que podemos cambiarlo sin editar manualmente la configuración de NGINX Plus y volver a cargarla.
• Las solicitudes de API a los servidores backend son independientes entre sí.

Descripción general de la solución

Además de utilizar la nueva función de subsolicitud de NGINX JavaScript, esta solución utiliza la función de almacenamiento de clave-valor de NGINX Plus, lo que permite realizar cambios de configuración de forma dinámica con la API de NGINX Plus .

Los siguientes gráficos ilustran los dos estilos de solicitud admitidos.

Estilo de solicitud de elemento final:

Estilo de solicitud de cadena de consulta:

En ambos ejemplos, el cliente necesita obtener información sobre un producto a través del catálogo, el inventario y los servicios de revisión. Envía una solicitud a NGINX Plus, ya sea pasando el número de artículo como parte de la URI o en la cadena de consulta. Luego, las solicitudes se envían a los tres servicios y las respuestas se agregan en una única respuesta al cliente.

Hay dos componentes necesarios para que esto funcione con NGINX Plus: un programa JavaScript y la configuración de NGINX Plus .

El programa JavaScript

La función JavaScript batchAPI() se llama para cada solicitud del cliente. Obtiene la lista separada por comas de las URI de API del almacén de valores clave y las itera, realizando una subsolicitud para cada una y especificando la función de devolución de llamada done() para procesar cada respuesta. En las solicitudes de estilo de elemento final, el último elemento del URI, almacenado en la variable $uri_suffix de NGINX, se pasa como cadena de consulta de cada subsolicitud, junto con cualquier otro argumento de cadena de consulta en el URI del cliente original. En las solicitudes de estilo de cadena de consulta, la cadena de consulta de las solicitudes del cliente se pasa como cadena de consulta de cada subsolicitud.

Las llamadas se realizan en el orden en que aparecen en el almacén de valores clave, pero son asincrónicas, por lo que las respuestas pueden volver en cualquier orden. Las respuestas se agregan en una sola respuesta al cliente en el orden en que se reciben. Aquí hay una versión mínima del programa JavaScript:

Una versión del programa JavaScript con manejo de errores, registro y comentarios más extensos está disponible en el repositorio Gist de GitHub como batch-api.js .

Configuración mínima de NGINX Plus

La siguiente configuración de NGINX Plus implementa los dos estilos de solicitud analizados anteriormente, utilizando un grupo de servidores ascendentes. Para simplificar las cosas, esta configuración supone que los servidores ascendentes pueden traducir una llamada del formato /myapi/ service / item# (estilo de elemento final) a /myapi/ service .php/?item= item# (estilo de cadena de consulta), que es el formato de URI “nativo” para PHP, el lenguaje para nuestros servicios de catálogo, inventario y revisión de muestra.

Para obtener una configuración más extensa de NGINX Plus que realiza la traducción por sí misma, consulte Ampliación de la configuración de NGINX para traducir URI a continuación.

Veamos el archivo de configuración sección por sección y expliquemos qué hace cada parte:

• Importar el archivo JavaScript :

• Defina un almacén de clave-valor para contener la lista de solicitudes de API donde el último elemento del URI identifica el argumento para el programa de API. La clave utiliza la variable $uri_prefix para capturar la parte del URI antes del último / :

  En NGINX Plus R16 y versiones posteriores, puede aprovechar dos funciones clave-valor adicionales:

  • Establezca un tiempo de expiración para las entradas en un almacén de clave-valor, agregando el parámetro de tiempo de espera a la directiva keyval_zone . Por ejemplo, para que cada URI por lotes expire diariamente, agregue timeout=1d .
  • Sincronice el almacén de valores clave en un clúster de instancias NGINX Plus, agregando el parámetro de sincronización a la directiva keyval_zone . También debe incluir el parámetro de tiempo de espera en este caso.

  Para obtener instrucciones sobre cómo configurar la sincronización para almacenes de clave-valor, consulte la Guía de administración de NGINX Plus .

• Defina otro almacén de valores clave para las API donde el argumento se identifica en la cadena de consulta. Aquí la clave ( $uri ) captura la URI completa, sin incluir la cadena de consulta:

• Define dos mapas para dividir el URI en dos partes para las API que aceptan solicitudes donde el argumento es el último elemento del URI. La variable $uri_prefix captura los elementos del URI antes del último / y $uri_suffix captura el último elemento:

• Define el grupo ascendente de servidores API (aquí, se ejecutan en el host local junto con NGINX Plus):

• Define el servidor virtual que maneja las solicitudes y subsolicitudes del cliente:

• Define una ubicación para manejar las solicitudes de cliente que usan el estilo de elemento final, que se indica a la función batchAPI configurando la variable $batch_api_arg_in_uri en on :

• Defina una ubicación para manejar las solicitudes de cliente que usan el estilo de cadena de consulta, que se indica a la función batchAPI configurando la variable $batch_api_arg_in_uri en off :

• Define la ubicación que maneja las subsolicitudes:

• Habilite la API NGINX Plus para que los datos puedan mantenerse en el almacén de clave-valor:

Aquí está la configuración completa:

Configuración de las solicitudes API por lotes

Estamos utilizando la función de almacenamiento de clave-valor de NGINX Plus para asignar solicitudes de clientes entrantes a un conjunto de solicitudes de API para ejecutar. La configuración de la sección anterior define almacenes de valores clave separados para los dos estilos de solicitud:

• El almacén de valores clave para el estilo de elemento final se llama batch_api y la clave es la variable $uri_prefix , que captura los elementos antes del / final del URI de la solicitud.
• El almacén de valores clave para el estilo de cadena de consulta se llama batch_api2 y la clave es la variable $uri , que captura la URI de solicitud completa sin la cadena de consulta.

En ambos almacenes de clave-valor, el valor asociado a cada clave es una lista de URI separados por comas que están disponibles en tiempo de ejecución en las variables $batch_api o $batch_api2 .

Para las solicitudes de estilo de elemento final, queremos asignar una solicitud de cliente para /batch-api/product a solicitudes a los tres servicios /myapi/catalog , /myapi/inventory y /myapi/review , de modo que una solicitud para /batch-api/product/14286 resulte en solicitudes a /myapi/catalog/14286 , /myapi/product/14286 y /myapi/review/14286 .

Para agregar estas asignaciones al almacén de clave-valor batch_api , enviamos la siguiente solicitud a la instancia de NGINX Plus que se ejecuta en la máquina local:

$ curl -iX POST -d '{"/batch-api/producto":"/myapi/catálogo,/myapi/inventario,/myapi/revisión"}' http://localhost/api/3/http/keyvals/batch_api

Para las solicitudes de estilo de cadena de consulta, queremos asignar una solicitud de cliente para /batch-api2/product a solicitudes a los tres servicios /myapi/catalog.php , /myapi/inventory.php y /myapi/review.php , de modo que una solicitud para /batch-api2/product?item=14286 resulte en solicitudes a /myapi/catalog?item=14286 , /myapi/product?item=14286 y /myapi/review?item=14286 .

Para agregar estas asignaciones al almacén de clave-valor batch_api2 , enviamos esta solicitud:

$ curl -iX POST -d '{"/batch-api2/producto":"/myapi/catálogo.php,/myapi/inventario.php,/myapi/revisión.php"}' http://localhost/api/3/http/keyvals/batch_api2

Ejecución de los ejemplos

Las mismas páginas PHP manejan las solicitudes realizadas en ambos estilos de solicitud. Para simplificar, suponemos que los servidores backend pueden traducir URI de estilo de elemento final ( /myapi/ service / item# ) en URI de estilo de cadena de consulta ( /myapi/ service .php?item= item# ). No es necesario traducir los URI de estilo cadena de consulta, ya que ese es el formato de URI “nativo” para los programas PHP.

Todos los servicios devuelven una respuesta en formato JSON que incluye el nombre del servicio y el argumento del elemento. Por ejemplo, una solicitud para /myapi/catalog.php?item=14286 da como resultado la siguiente respuesta de catalog.php :

{"servicio":"Catálogo","ítem":"14286"}

Aunque los programas PHP utilizados en estos ejemplos incluyen el nombre del servicio en la respuesta, este podría no ser el caso para todos los servicios. Para ayudar a hacer coincidir las respuestas con los servicios que las generaron, el programa JavaScript incluye la URI en la respuesta agregada.

Por ejemplo, la respuesta agregada para una solicitud de /batch-api/product/14286 es la siguiente (aunque el orden de las tres respuestas de los componentes puede variar):

[["/myapi/review/14286",{"service":"Review","item":"14286"}],["/myapi/inventory/14286",{"service":"Inventory","item":"14286"}],["/myapi/catalog/14286",{"service":"Catálogo","item":"14286"}]]

Ampliación de la configuración de NGINX Plus para traducir URI

Como se mencionó, la configuración mínima de NGINX Plus analizada anteriormente supone que los servidores API pueden traducir los URI del formato /myapi/ service / item# a /myapi/ service .php/?item= item# . También podemos implementar la traducción en la configuración de NGINX Plus realizando los siguientes cambios.

• Agregue un nuevo grupo ascendente para recibir las subsolicitudes:

• Agregue un nuevo servidor virtual para escuchar las solicitudes recibidas por el grupo de servicios ascendente. Cuando se reciben solicitudes de estilo de cadena de consulta, simplemente se envían al grupo ascendente api_servers porque el URI ya tiene la extensión .php . Cuando se reciben solicitudes de estilo de elemento final, se reescribe el URI de modo que se elimina el último elemento del URI y se convierte en un argumento de cadena de consulta:

• Cambie la ubicación de /myapi para actuar como proxy del nuevo grupo ascendente:

Aquí está la configuración completa:

Componentes adicionales

Los programas de JavaScript de muestra y las configuraciones de NGINX Plus se pueden adaptar a otros estilos de API, pero si desea realizar pruebas usando todos los componentes utilizados para crear esta publicación de blog, están disponibles en nuestro repositorio Gist en GitHub, incluida la configuración de NGINX Unit para servir las páginas PHP:

batch-api.js
catálogo.php
inventario.php
revisión.php
unidad.config

CONCLUSIÓN

Estos ejemplos muestran cómo agrupar solicitudes de API y proporcionar una respuesta agregada al cliente. El almacén de clave-valor de NGINX Plus nos permite configurar dinámicamente las solicitudes de API con la API de NGINX Plus . Los sistemas de API varían considerablemente en sus operaciones exactas, por lo que se pueden realizar numerosas mejoras en este ejemplo para adaptarlo a las necesidades de una API específica.

Puede comenzar a probar las subsolicitudes de JavaScript de NGINX con NGINX Open Source , pero si desea probar los ejemplos de procesamiento por lotes de API o probar otros casos de uso que aprovechan las características de NGINX Plus, como el almacén de clave-valor y la API de NGINX Plus , solicite una prueba gratuita de 30 días y comience a experimentar.