NSX-T API usage
Article ID: 379538
Updated On:
Products
Issue/Introduction
This KB will outline how to use the REST API using a tool such as Postman or command line with curl.
Curl can be used to point to the NSX-T managers or when instructed by support as the root user on an NSX-T manager appliance.
Environment
VMware NSX
Resolution
If using a tool such as Postman, you need to configure the authentication, usually this is accomplished by setting the authorization as Basic and adding the admin user and password.
Session based authentication is also possible, using an API to get the session cookie, further details on obtaining a session cookie can be found in the API guide Overview section.
The remainder of the document will be primarily focused on the use of basic authentication.
Note: While the admin user is normally used for authentication, any other local or remote user can be used for REST API authentication, if using a remote user, the domain suffix needs to be appended to the username, the domain must match a configured domain in NSX-T via either LDAP or vIDM, now known as Workspace ONE Access). The user needs to have the correct role assigned, see Role-Based Access Control for further details.
NSX-T API require headers when they are used, the API guide will outline which header is required for the specific API call, normally no header is required for a GET API call, POST/PUT API calls normally require the header 'Content-Type: application/json', make sure and review the API guide for required headers.
Methods
There are a number of HTTP methods used by NSX-T API's:
- GET - Returns data for the given API call.
- POST - This method is used to create a new resource and typically includes a body which is used to create the resource.
- PUT - This method is used to replace a resource with an updated version.
- DELETE - This method is used to remove a resource.
- PATCH - This method is used to update a resource, can be used to update specific portions of the resource, as apposed to the PUT which updates the complete resource.
The API guide will outline which API methods are allowed for the resource type.
Revision
NSX uses a employees a technique called Optimistic Concurrency Control, to prevent one API client overwriting another API clients update. There is a field called revision in an API result, when an update is made to a configuration, you need to pass the current revision number in the body, if this is incorrect, the API will fail with revision error. The reason for this is to prevent concurrent API calls, meaning you need to know the current version number to update a configuration. Once you do your API call, the revision number will increment by 1.
For example to change the revision, first we do a GET and note the current revision:
GET https://<nsx-mgr>/api/v1/configs/management
Result:{ "publish_fqdns": true,"_revision": 4}
Then we use this revision when doing the PUT API call, like this:
PUT https://<nsx-mgr>/api/v1/configs/management{ "publish_fqdns": true,"_revision": 4}
If we do a GET again, we note the revision has now incremented to 5.
{ "publish_fqdns": true,"_revision": 5}
Pagination
By default a API will present a number of results for a given API call, each API call has the default number in the API guide, if you configuration contains more than the default you need to paginate the results, bring the results back in different pages. The initial API will return cursor at the end of the results with the total number of results, to get the next page, you need to provide the cursor in the next API call, and the result will continue from that point, so for example, say you have 10,000 results, the default page size is 1,000, the first API will provide 1,000 results along with a cursor, you then need to submit the next API cursor, to get results 1,000 to 2,000 and so on until you have the complete 10,000 results.
Example:
GET https://<manager_ip>/api/v1/firewall/sections
Returns:
"section_type": "LAYER3", "stateful": true, "rule_count": 2, "is_default": false, "_create_user": "admin", "_create_time": 1574438858340, "_last_modified_user": ""****************", "_last_modified_time": 1671726034024, "_system_owned": false, "_protection": "NOT_PROTECTED", "_revision": 96 } ], "result_count": 1448, "sort_by": "position", "cursor": "0036588a382d-c679-480a-ab95-67aa0022ae04RmlyZXdhbGxTZWN0aW9u"
We see there are 1,448 results, the default page size is 1,000 and it returned a cursor, so we know pagination is active on this API, to get the next batch of results, by passing this cursor, we use:
GET https://<manager_ip>/api/v1/firewall/sections?cursor=0036588a382d-c679-480a-ab95-67aa0022ae04RmlyZXdhbGxTZWN0aW9u
Using curl to run API calls
We need to pass:
- A header type, normally application/json and defined with argument -H, not required if a GET method is used.
- A method type, use -X to define what type of method is being used 'PUT/POST/PATCH/DELETE'.
- The username and password used to run the API call, -u is used to define this, the password can be password or left empty to prompt the user to enter the password, if entered in the curl command, surround the username and password with single quotes.
- As the certificates are usually self signed, we bypass certificate checking using the -k option.
curl -k -u 'admin:<password>' -H 'Content-Type: application/json' -X PUT https://<nsx-mgr>/api/v1/configs/management -d @/tmp/data.txt
Adding data in an API call
Taken from the example above, if using curl to send the API call, we need to pass the data for the like of PUT/POST/PATCH API call, in an application like Postman, this can be achieved easily in the UI. When using curl, it needs to be passed, either via the command line or as a file with the content. The -d or --data flag can be used, followed by either the data or the path to the file with the data.
For example, passing the data in a file:
curl -k -u 'admin:<password>' -H 'Content-Type: application/json' -X PUT https://<nsx-mgr>/api/v1/configs/management -d @/tmp/data.txt
curl -k -u 'admin:<password>' -H 'Content-Type: application/json' -X PUT https://<nsx-mgr>/api/v1/configs/management --data @/tmp/data.txt
Note: Where /tmp/data.txt contains the data to be passed in the PUT API call, like this:
{ "publish_fqdns": true,
"_revision": 4
}
Or passing all the data on the command line:
curl -k -u 'admin:<password>' -H 'Content-Type: application/json' -X PUT https://<nsx-mgr>/api/v1/configs/management -d '{"publish_fqdns": true,"_revision": 4}'
If the method is GET, you can omit the -X GET argument, as GET is implied, if not other method is mentioned.
Additional Information
Feedback
