Manage Your APIs

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 that represents a specific version of your application’s API.
  • A Published API that exposes your API to traffic.
  • (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

API Definitions function as groups, or collections, of API resources. You can version API Definitions, and each version can have different API resources.

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

Configure Your API

On the Create API Definition page, provide the configuration details for your API.

  1. Provide a name for the API Definition.
    Tip:
    The Name field is not editable. The same name will be used for each version of an API Definition. Choose wisely! The name cannot include URL encoding, spaces, uppercase characters, or any of the following special characters: \ " [ ] { } ; * / ? : = & ~ ^ | # % ! < >.
  2. Choose how you would like to describe the API:
    Note:
    For each of the steps below, you can create a new resource for the Published API by selecting the Create New link.
  3. Provide a version. If a version isn’t provided, the default version, “unspecified”, will be used.
  4. (Optional) Provide a display name.
  5. (Optional) Provide a description.
    Note:
    If your API specification includes a description, that text will populate this field automatically when you add your OpenAPI spec.
  6. (Optional) Add tags.

Import an OpenAPI Specification

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

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

To import your spec by uploading a file:

  1. Select OpenAPI Specification.
  2. Select Import file.
  3. 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:

  1. Select OpenAPI Specification.
  2. Select Copy and paste specification text.
  3. 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.

  1. Select Configure Manually.
  2. Select Next to continue to the Resources page.
  3. Select Add API Resource.
  4. Select the Match Type to use for the API resource path.
  5. Specify the Path for the API resource.
    Tip:
    Path should start with /, for example, /userlookup/{userid}/attributes/{surname}.
  6. Select the HTTP method(s).
  7. (Optional) Document Your API.
  8. Review the API spec that will be sent to update the API Definition.
  9. Select Submit to save the API Definition.

Document Your API

Take 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 the first five steps if you’re continuing from the Define API Resources Manually section.
  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Services.

  3. On the Services menu, select APIs.

  4. On the API Definitions page, select the API Definition in the list that you want to create documentation for. A details pane is displayed.

  5. On the details pane for the API Definition, select Add Version.

  6. On the Add API Version page, select Resources.

  7. Select the pencil (edit) icon next to the method or methods that you want to document.

  8. Select Enable Documentation.

  9. Add a summary.

  10. (Optional) Add a description.

  11. (Optional) Add a request body description.

  12. (Optional) Add a sample request.

  13. Specify whether the request body is required.

  14. To add a parameter, select Add Parameter.

    1. Provide the parameter name.
    2. (Optional) Provide a parameter description.
    3. Select the parameter type.
    4. Select the parameter value.
    5. (Optional) Specify whether the parameter is required.
  15. To add a response, select Add Response.

    1. Provide the HTTP Response status code.
    2. Provide a description.
    3. (Optional) Provide a sample response in JSON format.
  16. Select Next to review the API spec that will be sent to update the API Definition.

  17. Select Submit to save the API Definition.

Review and Submit the API Configuration

  1. On the Create API Definition Resources page, review the Resources, then select Next.
  2. (Optional) Review or copy the API call.
  3. Select Submit to save the configuration.

You will see a brief notification that the API was saved successfully, then the API Definitions page will be displayed. You should now see your API Definition in the list.

Version Your API Definition

You can add Versions to your API Definition to track changes to your API as it evolves.

Note:
Each API Definition Version has a property called API version that easily differentiates one definition version from another. Typically an incremental pattern is set with v1 or 1 representing the first Definition version and v2 or 2 representing the second and so on.

For example, say your API version is “v1”. If your development cycle is anything like ours, you’re committing changes to your API and, maybe, creating release branches or tags at release time. When a release goes out, you can create a new Version to your API Definition that uses the commit or release tag SHA and contains the updated resources for that release. That way, you can ensure both that your outward-facing API reflects the current state of the code for the release and that the API Definition is easily traceable to a specific point in time in version control.

To add a new Version to your API Definition, take the steps below:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Services.

  3. On the Services menu, select APIs.

  4. On the API Definitions list page, select the API Definition that you want to version.

  5. Select Add Version.

  6. Enter the desired Version.

    Tip:
    Remember, this might not be your external API version. Instead, it could be the SHA for the most recent commit, or a semver release tag.
  7. Import your OpenAPI spec or enter the resources manually.

  8. Review your API Definition configuration, then select Submit to save your changes.

Publish an API

You will need at least one of each of the resources listed below to complete this section. If you have not already created the required resources, you will be able to do so while configuring the Published API.

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

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Services.
  3. On the Services menu, select APIs.
  4. On the API Definitions list page, select the API Definition for the API that you want to publish.
  5. Select Add Published API.

Configure the Published API

On the Create Published API Configuration page:

  1. Select the API Definition Version that you want to publish.
  2. (Optional) Provide a Base Path for the Published API.
  3. 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.
  4. Provide a Name and/or Display Name for the Published API.
  5. (Optional) Provide a description for the Published API.
  6. (Optional) Add tags.
  7. Select Next.

Define the Published API Deployment

Note:
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:

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

Define the Routing Rules

On the Create Published API Routing page:

  1. Select the Add New link to create a new App Component resource for the Published API.
  2. The Create App Component page has multiple sections.
    1. On the Create App Component Configuration page:

      1. Provide the name for your Component (required).
      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.
    2. 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.

        See Also:
        Refer to the Manage Locations topic for more information.
      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”.

        See Also:
        Refer to the NGINX Plus Admin Guide for more information about the available options.
      6. (Optional) Select the Session Persistence Type (applicable only to Web Components).

      7. (Optional) Select the Desired Proxy Settings (applicable only to Web Components).

        Tip:
        Hover your pointer over the info icon for each setting to learn about the expected values and requirements.
      8. Select Next.

    3. 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.
    4. On the Create App Component Authentication page:

      1. Select Add Authentication.
      2. Select an Identity Provider.
      3. Select a Credential Location.
      4. (Optional) Enable Conditional Access.
      5. Select Next.
    5. On the Create App Component Ingress page:

      1. (Optional) Set the desired Client Max Body Size.

        See Also:
        Refer to the NGINX module docs for more information about this option.
      2. Select Next.

    6. 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.
    7. 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.
    8. On the Create App Component Programmability page:

      Note:
      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.
         

    9. Select Next to review the API spec that will be sent to create the App Component.
  3. 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.
  4. Select Next to review the API spec that will be sent to create the Published API.
  5. 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.

What’s Next


This documentation applies to the following versions of NGINX Controller Documentation: 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15 and 3.16.