From OpenAPI to NGINX as an API Gateway Using a Declarative API

NGINX | June 17, 2024

NGINX has long been recognized as one of the top choices for powering high-performance web servers and load balancers. However, with the rise of microservices architectures and the need for efficient API management, NGINX has also become a popular choice for building API gateways.

In this blog, we will explore how to transform an OpenAPI schema definition into a fully functioning NGINX configuration running as an API Gateway with Web Application Firewall security and a Developer Portal using a declarative API approach.

We will provide step-by-step instructions and insights on how to leverage NGINX Plus to streamline your API management processes and ensure optimal performance for your applications.

Introducing the API Gateway

An API gateway serves as a central hub for managing and securing the communication between clients and backend services. It acts as a reverse proxy that sits between the client and the backend servers, routing incoming requests, and distributing them to the appropriate services. This allows for more efficient communication between the client and the services, as well as enabling the API gateway to handle tasks such as authentication, authorization, rate limiting, and caching.

Additionally, an API gateway can act as a security layer, protecting the backend services from potential threats and attacks. It can enforce security measures such as encryption, token-based authentication, and access control, ensuring that only authorized users can access the services. By consolidating and managing these security features in a single place, the API gateway helps to simplify the overall security architecture of the system and reduce the complexity of implementing security measures across multiple services.

NGINX Declarative API Project

The community-supported NGINX Declarative API project provides a set of declarative REST API for NGINX Instance Manager.

It can be used to manage NGINX Plus configuration lifecycles and to create NGINX Plus configurations using JSON service definitions. GitOps integration is supported when used with NGINX Instance Manager: source of truth is checked for referenced objects updates and NGINX configurations are automatically kept in sync.

OpenAPI schemas can be used to automatically configure NGINX as an API Gateway. Developer portal creation is supported through Redocly.

Prerequisites

To run the contents of this blog, you need:

A running instance of NGINX Instance Manager
A subscription (or 30-day free trial) for NGINX Plus and NGINX App Protect WAF. NGINX Agent must be installed to connect to NGINX Instance Manager and be part of the declarativeAPITest instance group
A Linux host (bare metal or VM) with docker and docker-compose to run the NGINX Declarative API project
Postman to submit the declarative API requests
A client host to run Postman

Lab Overview

After installing and running all prerequisites NGINX Instance Manager shows the NGINX Plus instance as online with NGINX App Protect WAF.

The NGINX Plus instance is part of the declarativeAPITest Instance Group

Deploying the Declarative API

The NGINX Declarative API project relies on the REST API provided by NGINX Instance Manager and provides the declarative, JSON-based abstraction. Follow these instructions to run the Declarative API Project:

1. Run docker ps to verify that Docker is running:

2. On the Linux host clone the Github repository:

3. Change to the docker-compose directory:

4. Use the nginx-dapi.sh script to start all containers through docker-compose. During the initial startup all docker images are built automatically:

5. Check running docker containers:

6. On the client host run Postman and import the NGINX Declarative API collection at https://raw.githubusercontent.com/f5devcentral/NGINX-Declarative-API/main/contrib/postman/NGINX%20Declarative%20API.postman_collection.json

7. Edit the Postman collection variables to adjust them to your environment:

8. Set the following variables:

ncg_host - hostname or IP address of the Linux host where the Declarative API docker-compose is running
ncg_port - TCP port for the NGINX Declarative API: 5000 is the default
nim_host - NGINX Instance Manager base URL (ie. https://nms.k8s.ie.ff.lan)
nim_username - NGINX Instance Manager authentication username
nim_password - NGINX Instance Manager authentication password

9. Save all changes on Postman

10. In the Postman collection browse to Petstore API Gateway RateLimit + JWT AuthN/AuthZ + WAF and open the request

The JSON declaration looks as follows:

The output section defines:

The NGINX Instance Manager server the Declarative API will publish the NGINX configuration to
TLS certificates and keys - these can be referenced by the URL of the source of truth where they are stored
NGINX App protect WAF security policies - these can be referenced by the URL of the source of truth where they are stored

The declaration section describes:

The NGINX server to be created
Whether or not TLS offload is performed
Where to log access and error entries
The /petstore base URI where the API Gateway configuration will be deployed and be made accessible to clients
The API Gateway configuration and developer portal to be published
How NGINX App Protect WAF is enabled, what security policy to use and where to log security violations to
How to authenticate and authorize client requests

The API Gateway declaration section describes how the declarative API will deliver its outcome.

The OpenAPI schema is referenced through its full URL:

Creation of the NGINX API Gateway configuration is requested, and the upstream server is defined. When NGINX reverse proxies requests to the upstream, the /petstore base URI is removed:

Developer portal creation and deployment under a specific URI is requested:

Clients authentication based on the specified client authentication profile is enforced for /user/login and /user/logout:

Clients authorization based on the specified client authorization profile is enforced for /user/login and /user/logout:

Rate limiting is applied for /user/login and /user/logout based on the specified profile:

12. Use the Postman Send button to publish the request to the declarative API. The response is similar to:

13. At this stage the NGINX instance is configured as an API Gateway, WAF security is enforced and the developer portal is published.