Transitioning to the New NGINX Plus API for Configuration and Monitoring

Transitioning to the New NGINX Plus API for Configuration and Monitoring

table.nginx-blog, table.nginx-blog th, table.nginx-blog td {
border: 2px solid black;
border-collapse: collapse;
}
table.nginx-blog {
width: 100%;
}
table.nginx-blog th {
background-color: #d3d3d3;
align: left;
padding-left: 5px;
padding-right: 5px;
padding-bottom: 2px;
padding-top: 2px;
line-height: 120%;
}
table.nginx-blog td {
padding-left: 5px;
padding-right: 5px;
padding-bottom: 2px;
padding-top: 5px;
line-height: 120%;
}
table.nginx-blog td.center {
text-align: center;
padding-bottom: 2px;
padding-top: 5px;
line-height: 120%;
}

One of the differentiating features of NGINX Plus is its use of shared memory to store additional metrics, runtime state, and configuration. This shared memory enables NGINX Plus to collect detailed extended status data, implement efficient health checks, and provide a dynamic configuration API.

In NGINX Plus R12 and earlier, we provided two APIs to access this shared memory – one to read extended status data (the status API), and one to manage upstream group configuration (the upstream_conf API). In NGINX Plus R13, we introduced a new, unified, NGINX Plus API and announced that the status and upstream_conf APIs are deprecated and will be removed in a later release.

The time is upon us – the R15 release is the last release to include support for these deprecated APIs. They will be removed in the R16 release:

This article summarizes the changes between the old and new APIs and provides instructions for end users and partners who have not yet migrated from the old APIs.

Recommended Configuration

The recommended configuration for the new NGINX Plus API is simpler than for the old status and upstream_conf APIs. The following configuration creates a simple virtual server that enables access to the API and to the live activity monitoring dashboard:

server {
    listen 192.168.1.23;
    # ...

    location /api {
        api [write=on];
        # directives limiting access to the API
    }

    location = /dashboard.html {
        root   /usr/share/nginx/html;
    }

    # Redirect requests made to the old dashboard
    location = /status.html {
        return 301 /dashboard.html;
    }
}

We strongly recommend that you secure access to the /api URI path. The NGINX Plus Admin Guide describes appropriate security schemes in more detail, and explains how to securely enable write access to the API (the DELETE, POST, and PATCH methods).

The write=on parameter is required if you want to use the API to reconfigure upstream groups or clear the set of collected statistics. It is not required to retrieve status information.

Replacing the Extended Status API

The deprecated status API supported HTTP GET operations and provided a single JSON document containing the internal NGINX Plus metrics. You could drill down to a smaller subset of the JSON document via a URI that addressed the subset.

The new NGINX Plus API supports HTTP GET operations to explore the API namespace and to retrieve one of a number of JSON documents that contain the NGINX Plus metrics. You can drill down to subsets using appropriate URIs, or use a fields list to obtain a smaller subset of the data. You can also use the DELETE method to reset statistics.

Differences between the Deprecated status API and the New NGINX Plus API

Any clients or services that use the deprecated status API must be updated to support the new NGINX Plus API. As you switch to the new API, note the following:

• The api directive replaces the status directive in NGINX Plus configuration files.
• The conventional URI for accessing the extended status data is /api, replacing /status.
• The conventional URI for accessing the live activity monitoring dashboard is /dashboard.html, replacing /status.html.
• Extended status data is no longer available as a single JSON document. For scalability and architectural reasons, it is split among separate documents. You might need to make several GET requests to get the data you want.

	Deprecated status API	New NGINX Plus API
Availability	NGINX Plus R15 and earlier	NGINX Plus R13 and later
Enabling directive	status	api [write=on]
Conventional URI in requests	/status	/api/version/
Supported methods	GET	GET, DELETE
Response payload	Single JSON document	Multiple JSON documents
Conventional dashboard location	/status.html	/dashboard.html

Using the New NGINX Plus API to Monitor NGINX Plus Status

The NGINX Plus Admin Guide provides a number of examples of using the NGINX Plus API to monitor NGINX Plus status.

Replacing the Upstream Conf API

The deprecated upstream_conf API provided a CLI‑focused way to manage the members of an upstream group. This API could be used to change the load‑balancing configuration dynamically, without requiring you to modify NGINX Plus configuration files and then reload the configuration.

The new NGINX Plus API can also be used to modify the members of an upstream group. You access upstream group configuration and metrics at this URI:

/api/version/http/upstreams/httpUpstreamName/servers/

You add, remove, and modify the parameters of upstream servers with the POST, DELETE, and PATCH methods respectively.

Differences between Deprecated upstream_conf API and new NGINX Plus API

Any clients or services that use the deprecated upstream_conf API must be updated to support the new NGINX Plus API. As you switch to the new API, note the following:

• The api directive replaces the upstream_conf directive in NGINX Plus configuration files.
• The conventional URI for dynamic reconfiguration is /api, replacing /upstream_conf.
• Parameters for operations are no longer provided as query strings. Instead, they operate in a RESTful fashion, using HTTP methods and JSON request bodies.

	Deprecated upstream_conf API	New NGINX Plus API
Availability	NGINX Plus R15 and earlier	NGINX Plus R13 and later
Enabling directive	upstream_conf	api write=on
Conventional URI	/upstream_conf	/api/version/
Typical operation	CLI, or HTTP GET with query string	RESTful, with JSON request body data
Supported methods	GET with query string	GET, DELETE, POST, PATCH

Using the New NGINX Plus API to Manage Upstream Groups

The NGINX Plus Admin Guide provides a number of examples showing how to manage upstream groups with the NGINX Plus API.

Conclusion

The new NGINX Plus API follows standard RESTful practices to access and update resources in the NGINX Plus status tree and configuration. It is easier for clients to access, and API versioning support makes it easier to maintain these clients. The API is documented in Open API Specification (Swagger) format; the swagger files are included in NGINX Plus or can be browsed online.

The API is the basis for future NGINX Plus innovations. In the R13 release, we also added a new key‑value store managed with the API, and in NGINX Plus R14 we extended it to support TCP/UDP (Stream) virtual servers and the drain operation for HTTP upstream servers. NGINX Plus R15 added API access for verifying that an NGINX Plus node is configured for cluster synchronization. Look for further innovations in releases to come.

Try the NGINX Plus API for yourself – start your free 30‑day trial today or contact us.

The post Transitioning to the New NGINX Plus API for Configuration and Monitoring appeared first on NGINX.

Source: Transitioning to the New NGINX Plus API for Configuration and Monitoring