Batching API Requests with NGINX Plus and the NGINX JavaScript Module

Batching API Requests with NGINX Plus and the NGINX JavaScript Module

The version of the NGINX JavaScript module (formerly called nginScript) released with NGINX Plus R15 can now issue subrequests, meaning that requests can be initiated in JavaScript code, allowing a whole new set of use cases to be addressed.

One of these use cases is batching API requests so that a single API request from a client can be turned into multiple API requests to a set of backend servers, and the responses aggregated into a single response to the client.

This post builds on the subrequest example in the NGINX Plus R15 announcement, which shows how to use subrequests to send the same request to two backend servers, and return only the first response to the client.

Introduction

The goal of this post is to provide working examples of API request batching that are simple and straightforward. The examples meet all of the following requirements:

• The HTTP GET method is used for all requests.
• All responses are in JSON format.

• Two styles of API requests are supported:

  • The argument to the API program is the final element of the URI. We call this the final‑element request style. In the example, a request for /batch-api/product/14286 spawns requests to /myapi/catalog/14286, /myapi/inventory/14286, and /myapi/review/14286.
  • The argument is identified in the query string of the URI. We call this the query‑string request style. In the example, a request for /batch-api2/product?item=14286 spawns requests to /myapi/catalog.php?item=14286, /myapi/inventory.php?item=14286, and /myapi/review.php?item=14286.

  Note that with either style there can be additional arguments in the query string.

• The set of subrequests triggered by a client request is dynamically configurable, meaning we can change it without manually editing the NGINX Plus configuration and reloading it.
• The API requests to the backend servers are independent of one another.

Solution Overview

In addition to using the new subrequest feature of NGINX JavaScript, this solution utilizes NGINX Plus’ key‑value store feature, allowing configuration changes to be made dynamically with the NGINX Plus API.

The following graphics illustrate the two supported request styles.

Final‑element request style:

Query‑string request style:

In both examples, the client needs to get information about a product from the catalog, inventory, and review services. It sends one request to NGINX Plus, either passing the item number as part of the URI or in the query string. Requests are then sent to the three services and the responses are aggregated into a single response to the client.

There are two components required to get this working with NGINX Plus: a JavaScript program and the NGINX Plus configuration.

The JavaScript Program

The JavaScript function batchAPI() is called for each client request. It gets the comma‑separated list of API URIs from the key‑value store and iterates through them, making a subrequest for each, and specifying the callback function done() to process each response. For final‑element style requests, the last element of the URI, stored in the NGINX variable $uri_suffix, is passed as the query string of each subrequest, along with any other query‑string arguments in the original client URI. For query‑string style requests, the query string from the client requests is passed as the query string of each subrequest.

The calls are made in the order they are listed in the key‑value store, but are asynchronous, so the responses can come back in any order. The responses are aggregated into one response to the client in the order in which they are received. Here is a minimal version of the JavaScript program:

A version of the JavaScript program with more extensive error handling, logging, and comments is also available in the GitHub Gist repo as batch-api.js.

Minimal NGINX Plus Configuration

The following NGINX Plus configuration implements the two request styles discussed above, using a group of upstream servers. To keeps things simple, this configuration assumes that the upstream servers are able to translate a call of the form /myapi/service/item# (final‑element style) to /myapi/service.php/?item=item# (query‑string style), which is the “native” URI format for PHP, the language for our sample catalog, inventory, and review services.

For a more extensive NGINX Plus configuration that performs the translation itself, see Expanding the NGINX Configuration to Translate URIs below.

Let’s look at the configuration file section by section and explain what each part does:

• Specify the JavaScript file:

• Define a key‑value store to hold the list of API requests where the last element of the URI identifies the argument to the API program. The key uses the $uri_prefix variable to capture the portion of the URI before the last /:

• Define another key‑value store for APIs where the argument is identified in the query string. Here the key ($uri) captures the entire URI, not including the query string:

• Define two maps to split the URI into two parts for APIs that accept requests where the argument is the last element of the URI. The $uri_prefix variable captures the URI elements before the last / and $uri_suffix captures the final element:

  <!– map $uri $uri_prefix {
  ~^(?

  .+)/.+$ $p;
  }

  map $uri $uri_suffix {
  ~^.+/(?.+)$ $s;
  } –>

• Define the upstream group of API servers:

• Define the virtual server that handles client requests and subrequests:

• Define a location to handle client requests that use the final‑element style, which is indicated to the batchAPI function by setting the $batch_api_arg_in_uri variable to on:

• Define a location to handle client requests that use the query‑string style, which is indicated to the batchAPI function by setting the $batch_api_arg_in_uri variable to off:

• Define the location that handles the subrequests:

• Enable the NGINX Plus API so that data can be maintained in the key‑value store:

curl -id '{"/batch-api/product":"/myapi/catalog,/myapi/inventory,/myapi/review"}' http://localhost:/api/3/http/keyvals/batch_api

curl -id '{"/batch-api2/product":"/myapi/catalog.php,/myapi/inventory.php,/myapi/review.php"}' http://localhost:/api/3/http/keyvals/batch_api2

{"service":"Catalog","item":"14286"}

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