API Overview

This topic gives an overview of the NGINX Instance Manager API.


This documentation applies to NGINX Instance Manager 2.0.0 and later.


Introduction

The NGINX Instance Manager API is a REST API that allows you to programmatically manage your NGINX data planes.

This document is intended to help people use the NGINX Instance Manager API.

Object Model

All NGINX Instance Manager resources are at the API path https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1.

The Instance Management module allows you to:

  • View metrics and information about data plane host systems and NGINX instances.
  • View and edit NGINX configurations.
  • Save NGINX configurations for future deployment.
  • Analyze saved and current configurations for syntactic errors.
  • Publish configurations to NGINX instances.
  • Scan the network to find unmanaged NGINX instances.
  • Manage certificates.
  • Create users, roles, and role permissions to manage RBAC.

Usage

Make an API call (using curl, Postman, etc). The API URL format is https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1.

For example, to list the data plane host systems in a GET call, you can run the following curl command:

curl -X GET "https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1/systems" -H  "accept: application/json"

API Docs

Examples of calls are available on the API Docs page, installed by default with NGINX Instance Manager. To view the API Docs click on the ‘?’ icon in the top right corner of your browser, or navigate to API docs page located https://<NGINX-INSTANCE-MANAGER-FQDN>/ui/docs.

API reference guide

Authentication

The NGINX Instance Manager supports basic authentication (not secure), JWT authentication, and OpenID Connect/OAuth2. You can make API requests with a valid JWT token or Basic Auth (demo only):

curl -X GET GET "https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1/systems" -H "Authorization: Basic YWRtaW..."
curl -X GET GET "https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1/systems" -H "Authorization: Bearer EY3q45..."

For more information about authentication options, you can read [Reference to Auth].

Encoding

All NGINX Instance Manager API endpoints expect and return JSON-formatted data by default.

All JSON-formatted data is expected to be encoded using UTF-8. If you do not specify a specific media type in an API call, then the API defaults to application/json.

Versioning

The introduction of backwards-incompatible changes to the NGINX Instance Manager API constitutes a major version change. This will be represented in the NGINX Instance Manager API version string. For example, to use a v2 API, you would use https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v2.

When any NGINX Instance Manager component requires a version change, we will release a new version of the entire API. In other words, you won’t see a mix of v1 and v2 objects in the same API.