API Overview

This topic gives an overview of the Instance Manager API.

Introduction

NGINX Management Suite Instance Manager provides a REST API that uses standard authentication methods, HTTP response codes, and verbs.

Object Model

The F5 NGINX Instance Manager REST API allows you to manage Instance Manager objects and the NGINX Management Suite platform programmatically. The Instance Manager API provides the following features:

  • 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.

API Reference Documentation

You can access the Instance Manager and Platform API Reference documentation through the NGINX Management Suite web interface.

To access the API Docs, take the steps below:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select API Documentation from the Launchpad menu.
  2. In the left-menu, select NIM and Platform API.

Usage

You can use tools such as curl or Postman to interact with the NGINX Instance Manager API. You can find The NGINX Instance Manager API URLs in the following format: https://<NMS_FQDN>/api/platform/<API_VERSION>.

Note:
When making API calls by using curl, Postman, or any other tool, include your authentication information with each call. Also include a -k to bypass TLS/SSL verification.

Alternatively, in the API Reference docs, you can also use the “Try it Out” function. Since you’re already logged into the NGINX Management Suite platform, the “Try it Out” function automatically includes authentication credentials.

To do so, take the steps below:

  1. Select the endpoint and action that you want to send. For example: POST /infrastructure/workspaces.
  2. Select the Try it Out button.
  3. If the endpoint accepts parameters, replace the placeholder examples in the request body with your desired values.
  4. Select the Execute button to send the request.
  5. When the request completes, the response appears in the user interface.

Authentication

To use the Instance Manager API, you need to use one of the following authentication methods:

  • Basic authentication
  • JSON Web Token (JWT)

Basic Authentication

To use basic authentication for API requests, include your base64-encoded credentials as a “Basic” token in the “Authorization” header. To set up base64-encoded credentials, run the following command:

echo -n <username>:<password> | base64

Now you can include those credentials with your API request. Here’s how you can do it with curl:

curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Basic <base64 encoded credentials>"

In this example, replace <NMS_FQDN> with your NGINX Management Suite’s fully qualified domain name and <API_VERSION> with the API version you want to use.


Security Consideration
You can use basic authentication for API requests, but you should be cautious: credentials are sent as base64-encoded text, which is not secure encryption. If your data gets intercepted, the encoding is easily reversible. In production environments where security is critical, we recommend switching to OpenID Connect (OIDC).

JSON Web Token

If your organization is using OIDC, you will be prompted to log in with your Identity Provider the first time you attempt to reach an API. After authenticating, you can request a JWT to use in subsequent API calls.

Note:
The means of requesting a token varies according to the Identity Provider; if you’re not sure which provider your organization uses, check with your system administrator or technical support team.

Once you have a JWT, set it up as a “Bearer” using the “Authorization” request header field, as shown in the example below.

curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Bearer <access token>"
Note:

For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history:

  1. JWTs: JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access.

  2. Shell history: Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your ~/.bash_history file. Alternatively, you can run the history -c command to erase your shell history.

Follow these practices to help ensure the security of your system and data.

Errors and Response Codes

Instance Manager uses standard HTTP response codes to indicate whether an API request succeeds or fails. Codes in the 2xx range mean the request succeeded. Codes in the 400 range mean the request failed due to the reason(s) indicated in the response message. Common reasons for 4xx responses are:

  • requests where required information is missing;
  • lack of or incorrect authentication credentials; and
  • requests that refer to resources that do not exist or are in use by other resources.

HTTP Status Codes

Response Code Meaning
200 Success: The request was received.
201 Success: Created the requested resource.
202 Success: The request was accepted and configuration is in process.
204 Success: Deleted the requested resource.
400 Bad Request: Required information is missing or incorrectly formatted.
401 Unauthorized: You are not logged in or do not have permission to access the requested resource.
404 Not found: The requested resource does not exist.
409 Conflict: The requested resource already exists or is referenced by another resource.

Encoding

All 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.

Pagination

Top-level Instance Manager API endpoints support fetching information about multiple resources (“lists”). Such requests may return large data sets (for example, GET /events and GET /instances). In these cases, you can define the size of the data set returned for each call and navigate amongst the pages of data by sending subsequent calls.

Parameters

Name Format Type Description Default value
page integer query page number 1
pageToken string query Transactional token used for pagination.
The token ensures consistency of the query results across requests for various pages of data. It provides a snapshot of the database contents from the time at which the query was received.
If pageToken is not provided with a page request, a token is automatically generated and will be returned in the response metadata. You should include the token in subsequent requests for pages in the query results.

Sending a query without a pageToken refreshes the query results.		 N/A
pageSize integer query Defines the number of returned items per page.

The maximum value is 100. If the value is greater, it is automatically scaled down to 100.

If pageSize=0, pagination is disabled and the full dataset will be returned in the response.
The response size is limited to 10,000 results. If the number of results exceeds 10,000 a warning is returned.		 100

Versioning

Each major version of the Instance Manager API is backward-compatible with the previous releases in that version. The introduction of backward-incompatible changes to the Instance Manager API constitutes a major version change. This will be represented in the <version> section of the API URI.

For example, to use a v2 API, you would send requests to https://<NMS_FQDN>/api/platform/v2.

When any Instance Manager component requires a version change, we will release a new version of the entire API. You will not see a mix of v1 and v2 objects in the same API.