This topic gives an overview of the Instance Manager API.
This documentation applies to NGINX Management Suite Instance Manager 2.0.0 and later.
The F5 Instance Manager (NIM) module is part of the NGINX Management Suite (NMS). The NIM module provides a REST API that uses standard authentication methods, HTTP response codes, and verbs.
The Instance Manager REST API allows you to manage NIM objects and the NMS platform programmatically. The NIM 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.
You can view the Instance Manager API Reference documentation in the NGINX Management Suite user interface. To access the API Docs, take the steps below:
- Log in to the NMS user interface.
- From the Launchpad, select the Docs card.
- Select NIM and Platform API from the Docs list in the sidebar. The API Reference documentation will then display.
Instance Manager supports authentication by using basic authentication or a JSON Web Token (JWT). You can get a JWT by logging in with an OpenID Connect (OIDC) Identity Provider.
For more information about the available authentication options for NGINX Management Suite, refer to Set Up Authentication.
You can make API requests with basic auth by sending the base64-encoded credentials as a “Basic” token in the “Authorization” request header, as shown in the example below.
curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Basic YWRtaW..."
Even when encoded, basic authentication is not secure. The use of basic auth is not recommended for production environments.
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.
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.
The JWT should be sent as a “Bearer” token in the “Authorization” request header, as shown in the example below.
curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"
You can use tools such as
curl or Postman to interact with the Instance Manager REST API.
The API URL follows the format
When making API calls by using
curl, Postman, or any other tool, you will need to provide your authentication information with each call.
You can also use the “Try it Out” function in the API Reference docs to send a call to the NIM API. You do not have to provide a means of authentication when sending API calls via the API Documentation UI because you are already logged in to the NMS platform.
To do so, take the steps below:
- Select the endpoint and action that you want to send. For example:
- Select the Try it Out button.
- If the endpoint accepts parameters, replace the placeholder examples in the request body with your desired values.
- Select the Execute button to send the request.
- When the request completes, the response appears in the UI.
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
|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.|
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
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.
||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.
Sending a query without a pageToken refreshes the query results.
||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.
The response size is limited to 10,000 results. If the number of results exceeds 10,000 a warning is returned.
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 NIM 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
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.