End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Manage Your APIs

Use the NGINX Controller API Manager to add APIs and control how your APIs are exposed and consumed.

Overview

The NGINX Controller API Management module provides full life cycle management for your APIs. This document provides a walkthrough of the steps needed to create, version, and publish your API using the NGINX Controller API Management module. When you have completed this guide, you should have the following resources:

An API Definition, which stores a collection of related API resources. It can be thought of as a folder.
An API Version, which describes a particular API and serves as the data contract. It describes available endpoints and operations on each endpoint and can also include API documentation.
A Published API, which represents an API Version that has been deployed to an NGINX Plus instance serving as an API Gateway.
(Optional) API documentation available via the Developer Portal.

Note:

You must have an API Management module license installed to complete the steps in this guide.

The API Management module is available to users with the predefined Admin or User Roles.

Create an API Definition

An API Definition functions as a collection of related API resources.

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Services.
On the Services menu, select APIs.
On the All APIs page, select Create and choose API Definition. Alternatively, you can also select Create API Definition from the Quick Actions list.

Create an API Version

An API Version describes a particular API. It can be thought of as an API specification.

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Services.
On the Services menu, select APIs.
On the All APIs page, select Create and choose API Version. Alternatively, you can also select Create API Version from the Quick Actions list.
Select an existing API Definition under which to group the API Version or select Create New to add a new API Definition.
Choose how you would like to describe the API:
1. OpenAPI specification
2. Configure manually
3. WSDL file (Currently only supports unauthenticated, unencrypted traffic)
Provide a version. If a version isn’t provided, the default version unspecified is used.
(Optional) Provide a display name.
(Optional) Provide a description.

Note:
If your API specification includes a description, that text populates this field automatically when you add your OpenAPI spec.
(Optional) Add tags.

Import an OpenAPI Specification

The APIM module supports import of a valid OpenAPI v3 specification formatted as valid JSON or YAML.

Note:
If your API spec includes documentation elements, the “Enable documentation” option is selected automatically. You do not need to take any additional steps to document your API.

To import your spec by uploading a file:

Select OpenAPI Specification.
Select Import file.
Drag and drop your file into the upload box, or select Browse to find and upload a file.

To import your spec by copying and pasting:

Select OpenAPI Specification.
Select Copy and paste specification text.
Paste or type your API in the space provided.

Once you have imported your API spec, select Next to continue to the Resources page.

Define API Resources Manually

Take the steps below to manually add your API resources.

Select Configure Manually.
Select Next to continue to the Resources page.
Select Add API Resource.
Select the Match Type to use for the API resource path.
Specify the Path for the API resource. Tip: Path should start with /, for example, /userlookup/{userid}/attributes/{surname}.
Select the HTTP method(s).
(Optional) Document Your API.
Review the API spec that will be submitted to create the API Version.
Select Submit to save the API Version.

Document Your API

Follow the steps below to document your API.

Note:

API documentation must follow the OpenAPI 2.0/3.0 Specification.

If you uploaded an API spec that contains documentation, you don’t need take any further steps to document your API.

Tip:
Skip to step 6 if you’re continuing from the Define API Resources Manually section.

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Services.
On the Services menu, select APIs.
On the All APIs page, select the API Version for which you want to create documentation. Click the pencil (edit) button to edit the API Version.
Select Resources.
Select the pencil (edit) icon next to the method or methods that you want to document.
Select Enable Documentation.
Add a summary.
(Optional) Add a description.
(Optional) Add a request body description.
(Optional) Add a sample request.
Specify whether the request body is required.
To add a parameter, select Add Parameter.
Provide the parameter name.
(Optional) Provide a parameter description.
Select the parameter type.
Select the parameter value.
(Optional) Specify whether the parameter is required.
To add a response, select Add Response.
Provide the HTTP Response status code.
Provide a description.
(Optional) Provide a sample response in JSON format.
Select Next to review the API spec that will be submitted to update the API Version.
Select Submit to save the API Version.

Import a Web Services Description Language (WSDL) file

Caution:
Currently, only HTTP is supported for SOAP-REST proxy traffic. Traffic will be unauthenticated and unencrypted, and as a result will be vulnerable to several security risks. It should be treated as a beta/preview feature.

The APIM module supports importing a WSDL file that describes a SOAP service.

To import your spec by uploading a file:

Select WSDL File.
Select Import file.
Drag and drop your file into the upload box, or select Browse to find and upload a file.

To import your spec by copying and pasting:

Select WSDL file.
Select Copy and paste WSDL text.
Paste or type your API in the space provided.

Once you’ve imported your API spec, select Next to continue to the Resources page. Note that you need to submit the API spec before you can modify the Resources and Schema. Select Submit to save the API Version.

Modify Schema and Resources for an API Version created from a WSDL file

Take the following steps to Edit add your API Version:

On the All APIs page, select the API Version that was created from a WSDL
Select Next to continue to the Resources page.
For each SOAP operation, choose the appropriate equivalent REST Method.
(optional) Modify the Path for the API resource as desired.

Tip:
Path should start with /, for example, /userlookup/{userid}/attributes/{surname}.
Select Next to continue to the Schema page
(Optional) For each JSON schema, modify the Property as desired
Review the API spec that will be submitted to create the API Version.
Select Submit to save the API Version.

Publish an API

You need at least one of each of the resources listed below to complete this section. If you haven’t already created the required resources, you can do so while configuring the Published API.

(required to add Authentication to the Published API Component).

Tip:
You can connect one or more Developer Portals to your Published API to host your API documentation. This can be done either when creating or editing your Published API, or independently via the API Quick Actions menu.

Add a Published API

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Services.
On the Services menu, select APIs.
On the All APIs page, select the API Version that you want to publish.
Select Add Published API.

Configure the Published API

On the Create Published API Configuration page:

Select the API Definition Version that you want to publish.
(Optional) Provide a Base Path for the Published API.
Specify whether the Strip Base Path parameter is required.

Note:
The Strip Base Path option modifies the path that is passed from the Gateway to the upstream host. When the option is selected, the base path will be removed from the original request when the request is passed to the upstream host. If the option is not selected, the original request – including the base path – is passed from the Gateway to the upstream host.
Provide a Name and/or Display Name for the Published API.
(Optional) Provide a description for the Published API.
(Optional) Add tags.
Select Next.

Define the Published API Deployment

For each of the steps below, you can create a new resource for the Published API by selecting the Create New link.

On the Create Published API Deployment page:

Select the Environment that the Published API belongs to.
Select the App that the Published API represents.
Select the Gateway(s) that will expose the Published API.
Select the Dev Portal(s) that will host documentation for the Published API.
Select Next.

Define the Routing Rules

On the Create Published API Routing page:

Select the Add New link to create a new App Component resource for the Published API. The Create App Component page has multiple sections.
On the Create App Component Configuration page:
1. Provide the name for your Component.
2. (Optional) Provide a Display Name.
3. (Optional) Provide a Description.
4. (Optional) Add any desired tags.
5. (Optional) Select the error response format.
6. Select Next.
On the Create App Component Workload Groups page:
1. Provide a Workload Group Name.
2. (Optional) Select a Location. The default Location is ‘Unspecified’. This value is applied automatically to “bring your own” (BYO) NGINX Plus instances that were not deployed by NGINX Controller.
3. Define the backend workload URIs.
4. (Optional) Define the DNS Server.
5. (Optional) Select the Load Balancing Method. The default value is Round Robin.
6. (Optional) Select the Session Persistence Type (applicable only to Web Components).
7. (Optional) Select the Desired Proxy Settings (applicable only to Web Components).
8. Select Next.
  See Also:
  - Refer to the Manage Locations topic for more information.
  - Refer to the NGINX Plus Admin Guide for more information about the available options.
  Tip:
  Hover your pointer over the info icon for each setting to learn about the expected values and requirements.
On the Create App Component Rate Limiting page:
1. Enable Rate Limiting and select a Key.
2. Select options for Rate and Units.
3. (Optional) Select options for Excess Request Processing and Ignore Initial N Requests.
4. Select options for Reject Status Code.
5. Select Next.
On the Create App Component Authentication page:
1. Select Add Authentication.
2. Select an Identity Provider.
3. Select a Credential Location.
  1. (Optional) Enable Conditional Access.
4. Select Next.

Important:
The Advanced Security features require an NGINX Controller API Management Advanced Security license.

On the Create App Components Advanced Security page:
1. (Optional) Select Enable Web Application Firewall (WAF) to monitor and block suspicious requests or attacks.
2. (Optional) Select Monitor Only to allow traffic to pass without being rejected. Security events are still generated and metrics are still collected. Refer to About App Security Analytics for more information.
3. (Optional) Add the signature(s) that you want WAF to ignore. You can specify multiple signatures as a comma-separated list.
4. Select Next
See Also:
Refer to the Default WAF Policy topics to learn more about the default protection provided by NGINX App Protect.
On the Create App Component Ingress page:
1. (Optional) Set the desired Client Max Body Size.
2. Select Next.
See Also:
Refer to the NGINX module docs for more information about this option.
On the Create App Component Monitoring page:
1. (Optional) Enable Health Monitoring and define the desired Monitoring Request and Response. Health Monitoring is disabled by default.
2. (Optional) Specify the URI to use in health check requests (applicable only to Web Components). The default is /. For TCP/UDP Components, specify the Send string.
3. (Optional) Specify the port to use when connecting to a server to perform a health check. The server port is used by default.
4. (Optional) Set the interval to wait between two consecutive health checks. The default is 5 seconds.
5. (Optional) Specify the number of consecutive passed health checks that must occur for a server to be considered healthy. The default is 1.
6. (Optional) Specify the number of consecutive failed health checks that must occur for a server to be considered unhealthy. The default is 1.
7. (Optional) Specify the default state for the server. The default state is HEALTHY.
8. (Optional) Specify the starting HTTP status code to match against (applicable only to Web components).
9. (Optional) Specify the ending HTTP status code to match against (applicable only to Web components).
10. (Optional) Select whether a response should pass in order for the health check to pass (applicable only to Web components). By default, the response should have status code 2xx or 3xx.
11. Select Next.
See Also:
Refer to the NGINX module docs for more information about these options.
On the Create App Component Logs page:
1. (Optional) Select the logs to enable:
  
  § Error Log
  
  § Access Log
2. (Optional) Specify the log format to use.
3. Select Next.
See Also:
Refer to the NGINX docs for more information about these options.
On the Create App Component Programmability page:

The following settings are applicable only to Web components.
1. (Optional) Select Add URI Redirects and define the desired redirect condition(s).
2. (Optional) Select Add URI Rewrite and define the desired rewrite pattern(s).
3. (Optional) Select Add Request Header Modification and define how to modify the request header.
4. (Optional) Select Add Response Header Modification and define how to modify the response header.
5. Select Next.
See Also:
Refer to the NGINX module docs for more information about these options.
1. Select Next to review the API spec that will be sent to create the App Component.
2. Drag and drop resources one at a time, or move multiple resources by selecting the checkboxes next to the desired resources, from the Unrouted column to the desired Component in the Components list. You can use the search bar to narrow down the list. Note: Resources can be dragged between Components and back to the Unrouted section either one at a time or by multi-select.
3. Select Next to review the API spec that will be sent to create the Published API.
4. Select Submit to create the Published API.

Create a Developer Portal

Once you have created an API Definition and a Published API, you can host your API in a Developer Portal.

From the API Definitions page, select Create Dev Portal from the Quick Actions menu. Then, follow the steps in Create a Developer Portal to create, customize, and publish your Dev Portal.