Deploy Nginx Plus as API Gateway: Nginx

Learn how the famous Nginx server (an essential for microservices) can be used as an API gateway.

At the heart of modern application architectures are HTTP APIs. HTTP enables applications to be built quickly and maintained easily. HTTP APIs provide a common interface regardless of the scale of the application, from single-purpose microservices to all-encompassing monoliths. By using HTTP, the advances in web application delivery that support hyperscale Internet properties can also be used to provide reliable and high-performance API delivery.

[[275822]]

For an excellent introduction to the importance of an API Gateway to microservices applications, see Building Microservices: Using an API Gateway on our blog.

As the leading high-performance, lightweight reverse proxy and load balancer, NGINX Plus has the advanced HTTP processing capabilities needed to handle API traffic. This makes NGINX Plus an ideal platform for building an API gateway. In this blog post, we describe many common API gateway use cases and show how to configure NGINX Plus to handle them in an efficient, scalable, and easy-to-maintain manner. We describe a complete configuration that can form the basis of a production deployment.

Note: Unless otherwise noted, all information in this article applies to both NGINX Plus and NGINX Open Source.

Introducing the Warehouse API

The main function of an API Gateway is to provide a single, consistent entry point for multiple APIs, regardless of how they are implemented or deployed on the backend. Not all APIs are microservice applications. Our API Gateway needs to manage existing APIs, monoliths, and applications that are partially transitioning to microservices.

Throughout this blog post, we refer to a hypothetical inventory management API, the “Warehouse API.” We use example configuration code to illustrate different use cases. The Warehouse API is a RESTful API that consumes JSON requests and produces JSON responses. However, using JSON is not a limitation or requirement of NGINX Plus when deployed as an API gateway; NGINX Plus is agnostic about the architectural style and data format used by the API itself.

The Warehouse API is implemented as a collection of discrete microservices and published as a single API. The inventory and pricing resources are implemented as separate services and deployed to different backends. So the path structure of the API is:

 api └── warehouse
 ├── inventory
 └── pricing

For example, to query the current warehouse inventory, the client application would make an HTTP GET request to /api/warehouse/inventory.

Organizing NGINX Configuration

One advantage of using NGINX Plus as an API gateway is that it can perform that role, acting simultaneously as a reverse proxy, load balancer, and web server for existing HTTP traffic. If NGINX Plus is already part of your application delivery stack, then there is generally no need to deploy a separate API gateway. However, some of the default behaviors expected of an API gateway differ from those expected for browser-based traffic. For this reason, we separate the API gateway configuration from any existing (or future) configuration for browser-based traffic.

To achieve this separation, we created a configuration layout that supports a multi-purpose NGINX Plus instance and provides a convenient structure for automating configuration deployments through CI/CD pipelines. The resulting directory structure under /etc/nginx is shown below.

 etc/ └── nginx/
 ├── api_conf.d/ ............................. Subdirectory for per-API configuration
 │ └── warehouse_api.conf ...... Definition and policy of the Warehouse API
 ├── api_backends.conf ........................ The backend services (upstreams)
 ├── api_gateway.conf ........................ Top - level configuration for the API gateway server
 ├── api_json_errors.conf ............ HTTP error responses in JSON format
 ├── conf.d/
 │ ├── ...
 │ └── existing_apps.conf
 └── nginx.conf

All API Gateway configuration directories and file names are prefixed with api_. Each of these files and directories enables different features and functionality of the API Gateway and are described in detail below.

Defining the top-level API gateway

All NGINX configurations begin with the main configuration file, nginx.conf. To read in the API Gateway configuration, we add a directive to the http block of nginx.conf that references the file api_gateway.conf that contains the gateway configuration (line 28 below). Note that the default nginx.conf file uses the include directive to pull in the browser-based HTTP configuration from the conf.d subdirectory (line 29). This blog post makes extensive use of include directives to improve readability and automate certain parts of the configuration.

 include /etc/nginx/api_gateway.conf; # All API gateway configuration
 include /etc/nginx/conf.d/*.conf; # Regular web traffic

The api_gateway.conf file defines a virtual server that exposes NGINX Plus as an API gateway to clients. This configuration exposes all APIs published by the API gateway at a single entry point, https://api.example.com/ (line 13), protected by TLS configured on lines 16 to 21. Note that this configuration is purely HTTPS—there is no plaintext HTTP listener. We want API clients to know the correct entry point and make HTTPS connections by default.

 log_format api_main '$remote_addr - $remote_user [$time_local] "$request"'  
 '$status $body_bytes_sent "$http_referer" "$http_user_agent"'  
 '"$http_x_forwarded_for" "$api_name"' ; 
  
 include api_backends.conf;
 include api_keys.conf; 
  
 server {
 set $api_name -; # Start with an undefined API name , each API will update this value
 access_log /var/log/nginx/api_access.log api_main; # Each API may also log to a separate file 
  
 listen 443 ssl;
 server_name api.example.com; 
  
 #TLS config
 ssl_certificate /etc/ssl/certs/api.example.com.crt;
 ssl_certificate_key /etc/ssl/private/api.example.com.key ;
 ssl_session_cache shared:SSL:10m;
 ssl_session_timeout 5m;
 ssl_ciphers HIGH:!aNULL:!MD5;
 ssl_protocols TLSv1.1 TLSv1.2; 
  
 # API definitions, one per file
 include api_conf.d/*.conf; 
  
 # Error responses
 error_page 404 = @400; # Invalid paths are treated as bad requests
 proxy_intercept_errors on ; # Do not send backend errors to the client
 include api_json_errors.conf; # API client friendly JSON error responses
 default_type application/json; # If no content-type then assume JSON
 }

This configuration is static - the details of the individual APIs and their backend services are specified in the file referenced by the include directive on line 24. Lines 27 to 30 deal with logging defaults and error handling, and are discussed in the Response to Errors section below.

Single-service vs. microservice API backends

Some APIs can be implemented on a single backend, but for reasons of resiliency or load balancing, we usually expect multiple APIs to exist. With a microservice API, we define a separate backend for each service; together they act as a complete API. Here, our Warehouse API is deployed as two separate services, each with multiple backends.

 upstream warehouse_inventory {
 zone inventory_service 64k;
 server 10.0.0.1:80;
 server 10.0.0.2:80;
 server 10.0.0.3:80;
 } 
  
 upstream warehouse_pricing {
 zone pricing_service 64k;
 server 10.0.0.7:80;
 server 10.0.0.8:80;
 server 10.0.0.9:80;
 }

All backend API services for all APIs published by the API Gateway are defined in api_backends.conf. Here we use multiple IP address-port pairs in each block to indicate where the API code is deployed, but hostnames can also be used. NGINX Plus subscribers can also take advantage of dynamic DNS load balancing, automatically adding new backends to the runtime configuration.

Defining the Warehouse API

This section of the configuration first defines the valid URIs for the Warehouse API, and then defines the public strategy for handling requests to the Warehouse API.

 # API definition
 #
 location /api/warehouse/inventory {
 set $upstream warehouse_inventory;
 rewrite ^ /_warehouse last ;
 } 
  
 location /api/warehouse/pricing {
 set $upstream warehouse_pricing;
 rewrite ^ /_warehouse last ;
 } 
  
 # Policy section  
 #
 location = /_warehouse {
 internal;
 set $api_name "Warehouse" ; 
  
 # Policy configuration here (authentication, rate limiting, logging, more...) 
  
 proxy_pass http://$upstream$request_uri;
 }

The Warehouse API defines a number of blocks. NGINX Plus has an efficient and flexible system for matching a request URI to a portion of the configuration. In general, requests are matched by the most specific path prefix, and the order of the location directives is not important. Here, on lines 3 and 8, we define two path prefixes. In each case, the $upstream variable is set to the name of the upstream block that represents the backend API service for the inventory and pricing services, respectively.

The goal of this configuration is to separate the API definition from the policies that govern how the API is delivered. To this end, we minimize the configuration shown in the API definition section. After determining the appropriate upstream group for each location, we stop processing and use instructions to find the policy for the API (line 10).

Use rewrite directives to move processing to the API policy section

The result of the rewrite directive is that NGINX Plus searches for a location block that matches a URI that begins with /_warehouse. The location block on line 15 uses the = modifier to perform an exact match, which speeds up processing.

At this stage, our policy section is pretty simple. The location block itself is marked on line 16, which means that clients cannot make requests to it directly. The $api_name variable is redefined to match the name of the API so that it appears correctly in log files. Finally, requests are proxied to the upstream group specified in the API definition section, using the $request_uri variable - which contains the original request URI, unmodified.

Choose between broad or precise API definition

There are two approaches to API definition - broad and precise. The most appropriate approach for each API depends on the security requirements of the API and whether the backend service needs to handle invalid URIs.

In warehouse_api_simple.conf, we use the broad approach for the Warehouse API by defining URI prefixes on lines 3 and 8. This means that any URI starting with either prefix is ​​proxied to the corresponding backend service. Using prefix-based location matching, API requests to the following URIs are all valid:

• /api/warehouse/inventory
• /api/warehouse/inventory/
• /api/warehouse/inventory/foo
• /api/warehouse/inventoryfoo
• /api/warehouse/inventoryfoo/bar/

If the only consideration is to proxy each request to the correct backend service, the broad approach provides the fastest processing and the most compact configuration. On the other hand, the precise approach enables the API Gateway to understand the full URI space of the API by explicitly defining the URI path of each available API resource. Taking the precise approach, the following configuration for the Warehouse API uses a combination of exact matching (=) and regular expressions (~) to define each URI.

 location = /api/warehouse/inventory { # Complete inventory
 set $upstream inventory_service;
 rewrite ^ /_warehouse last ;
 } 
  
 location ~ ^/api/warehouse/inventory/shelf/[^/]*$ { # Shelf inventory
 set $upstream inventory_service;
 rewrite ^ /_warehouse last ;
 } 
  
 location ~ ^/api/warehouse/inventory/shelf/[^/]*/box/[^/]*$ { # Box on shelf
 set $upstream inventory_service;
 rewrite ^ /_warehouse last ;
 } 
  
 location ~ ^/api/warehouse/pricing/[^/]*$ { # Price for specific item
 set $upstream pricing_service;
 rewrite ^ /_warehouse last ;
 }

This configuration is more verbose, but more accurately describes the resources implemented by the backend service. This has the advantage of protecting the backend service from malformed client requests, at the cost of some small additional overhead for regular expression matching. With this configuration, NGINX Plus accepts some URIs and rejects others as invalid:

With precise API definitions, existing API documentation formats can drive the configuration of the API Gateway. It is possible to automate NGINX Plus API definitions from the OpenAPI Specification (formerly known as Swagger). Example scripts for this purpose are provided in the Gists of this blog post.

Rewriting client requests

As an API evolves, sometimes breaking changes occur that require updating clients. One such example is renaming or moving an API resource. Unlike a web browser, an API gateway cannot send a redirect (code 301) to its clients naming the new location. Fortunately, when modifying an API client is impractical, we can rewrite client requests dynamically.

In the example below, we can see on line 3 that the pricing service was previously implemented as part of the inventory service: the rewrite directive converts requests for the old pricing resource to the new pricing service.

 # Rewrite rules
 #
 rewrite ^/api/warehouse/inventory/item/price/(.*) /api/warehouse/pricing/$1; 
  
 # API definition
 #
 location /api/warehouse/inventory {
 set $upstream inventory_service;
 rewrite ^(.*)$ /_warehouse$1 last ;
 } 
  
 location /api/warehouse/pricing {
 set $upstream pricing_service;
 rewrite ^(.*) /_warehouse$1 last ;
 } 
  
 # Policy section  
 #
 location /_warehouse {
 internal;
 set $api_name "Warehouse" ; 
  
 # Policy configuration here (authentication, rate limiting, logging, more...) 
  
 rewrite ^/_warehouse/(.*)$ /$1 break; # Remove /_warehouse prefix
 proxy_pass http://$upstream; # Proxy the rewritten URI
 }

Dynamically rewriting the URI means that when we finally proxy the request on line 26, we can no longer use the $request_uri variable (as we did on line 21 of warehouse_api_simple.conf). This means that we need to use slightly different rewrite directives on lines 9 and 14 of the API definition section in order to preserve the URI when processing switches to the policy section.

Responding to Errors

One of the main differences between HTTP APIs and browser-based traffic is how errors are communicated to clients. When NGINX Plus is deployed as an API gateway, we configure it to return errors in a way that best suits the API client.

 # Error responses
 error_page 404 = @400; # Invalid paths are treated as bad requests
 proxy_intercept_errors on ; # Do not send backend errors to the client
 include api_json_errors.conf; # API client friendly JSON error responses
 default_type application/json; # If no content-type then assume JSON

The top-level API Gateway configuration includes a section that defines how error responses are handled.

The directive on line 27 specifies that NGINX Plus returns an error instead of a default error when a request does not match any API definition. This (optional) behavior requires that API clients make requests only to valid URIs included in the API documentation and prevents unauthorized clients from discovering the URI structure of an API published through the API Gateway.

Line 28 refers to an error generated by the backend service itself. Unhandled exceptions may contain stack traces or other sensitive data that we do not want to send to the client. This configuration provides further protection by sending standardized errors to the client.

The full list of error responses is defined in a separate configuration file referenced by the include directive on line 29, the first few lines of which are shown below. This file can be modified if a different error format is preferred by changing the default_type value on line 30 to match. You can also use separate include directives in the policy section of each API to define a set of error responses that override the defaults.

 error_page 400 = @400;
 location @400 { return 400 '{"status":400,"message":"Bad request"}\n' ; } 
  
 error_page 401 = @401;
 location @401 { return 401 '{"status":401,"message":"Unauthorized"}\n' ; } 
  
 error_page 403 = @403;
 location @403 { return 403 '{"status":403,"message":"Forbidden"}\n' ; } 
  
 error_page 404 = @404;
 location @404 { return 404 '{"status":404,"message":"Resource not found"}\n' ; }

With this configuration, a client request for an invalid URI will receive the following response.

 $ curl -i https://api.example.com/foo
 HTTP/1.1 400 Bad Request
 Server: nginx/1.13.10
 Content-Type: application/json
 Content-Length: 39
 Connection : keep-alive 
  
 { "status" :400, "message" : "Bad request" }

Implementing Authentication

It is uncommon to publish APIs without some form of authentication to protect them. NGINX Plus provides several ways to protect APIs and authenticate API clients. See the documentation for information on IP address-based access control lists (ACLs), digital certificate authentication, and HTTP Basic authentication. Here, we focus on API-specific authentication methods.

API Key Authentication

API keys are shared secrets known to clients and the API Gateway. They are essentially long, complex passwords issued to API clients as long-term credentials. Creating an API key is simple - just encode a random number, as shown in this example.

 openssl rand -base64 18 7B5zIqmRGXmrJTFmKa99vcit

On line 6 of the top-level API Gateway configuration file, api_gateway.conf, we include a file called api_keys.conf, which contains the API keys for each API client, identified by the client name or other description.

 map $http_apikey $api_client_name {
 default   "" ; 
  
 "7B5zIqmRGXmrJTFmKa99vcit"   "client_one" ;
 "QzVV6y1EmQFbbxOfRCwyJs35"   "client_two" ;
 "mGcjH8Fv6U9y3BVF9H3Ypb9T"   "client_six" ;
 }

The API key is defined in the block. The map directive has two parameters. The first defines the location of the API key, in this case the apikey HTTP header of the client request captured in the $http_apikey variable. The second parameter creates a new variable ($api_client_name) and sets it to the value of the second parameter on the line where the first parameter matches the key.

For example, when the client provides the API key 7B5zIqmRGXmrJTFmKa99vcit, the $api_client_name variable is set to client_one. This variable can be used to check for authenticated clients and included in log entries for more detailed auditing.

The format of the map block is simple and easy to integrate into automated workflows to generate an api_keys.conf file from an existing credential store. API key authentication is enforced by the policy section of each API.

 # Policy section  
 #
 location = /_warehouse {
 internal;
 set $api_name "Warehouse" ; 
  
 if ($http_apikey = "" ) {
 return 401; # Unauthorized (please authenticate)
 }
 if ($api_client_name = "" ) {
 return 403; # Forbidden (invalid API key )
 } 
  
 proxy_pass http://$upstream$request_uri;
 }

Clients should present their API key in the apikey HTTP header. If this header is missing or empty (line 20), we send a 401 response to tell the client that authentication is required. Line 23 handles the case where the API key doesn't match any of the keys in the map block - in this case, the default parameters on line 2 of api_keys.conf set $api_client_name to an empty string - we send a 403 response to tell the client that authentication failed.

With this configuration, the Warehouse API can now implement API key authentication.

 $ curl https://api.example.com/api/warehouse/pricing/item001
 { "status" :401, "message" : "Unauthorized" }
 $ curl -H "apikey: thisIsInvalid" https://api.example.com/api/warehouse/pricing/item001
 { "status" :403, "message" : "Forbidden" }
 $ curl -H "apikey: 7B5zIqmRGXmrJTFmKa99vcit" https://api.example.com/api/warehouse/pricing/item001
 { "sku" : "item001" , "price" :179.99}

JWT Authentication

JSON Web Tokens (JWT) are increasingly being used for API authentication. Native JWT support is unique to NGINX Plus, and it is possible to verify JWTs on our blog, as described in Authenticating API Clients with JWT and NGINX Plus.