The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter provides an overview for using the Representational State Transfer (REST) application programming interface (API) with the Cisco Nexus 1000V Series Switches.
The Cisco Nexus 1000V Virtual Supervisor Module (VSM) supports the RESTful webservices API and provides limited functionality through this service.
You can create, read, update, and delete an object on the Cisco Nexus 1000V VSM using the RESTful web services API. REST is based on HTTP and, therefore, these four operations are in turn mapped to GET, POST, and DELETE HTTP operations. In order to call any REST function, you can use tools such as a web browser, the cURL tool, and Windows PowerShell.
REST tunneling is a special resource api/cli to which CLI commands may be posted to HTTP (HTTP POST) and CLI responses are returned. For example, to create a port-profile you type the following:
The following is the basic construct of a REST URL:
The resource locator consists of two parts:
For example, in the following URL, n1k is the namespace and license is the object name.
If you are using curl or a browser extension such as REST Console to issue REST calls, type the URL. For example, if you want to get the license information of your VSM that has an IP address of 10.10.10.2, you type the URL as follows:
To access the same through cURL, you use the following format:
Note You can view detailed information pertaining to all the REST resources. To get this information, you must append ?meta to the URI.
Every REST API function is associated with a namespace. Functions that are specific to Nexus 1000V on Hyper-V are under the n1k namespace. The n1k namespace is found when the following URL is entered:
In the above output, span, vpath, user, port-profile, vlan, and vnode are the functions that are a part of the global namespace and n1k is the namespace that includes the Hyper-V specific functions.
To find all the functions under the n1k namespace, enter the following URL:
The REST API supports the JavaScript Object Notation (JSON) format for a response. For JSON response, specify Accept: application/json in the HTTP header as shown in the following example:
To specify the JSON response format through cURL, use the following:
The following example shows the response received in the JSON format:
The REST API supports the XML format for a response. For XML response, specify Accept: application/xml in the HTTP header as shown in the following example:
To specify the XML response format through cURL, use the following:
The following example shows the response received in the XML format:
To create an object, you must construct an HTTP POST request:
The request must have a payload that contains JavaScript Object Notation- (JSON)-formatted fields that are part of the newly created object:
For example, to create an IP address pool with a pool name of pool1 on a VSM with an IP address of 10.10.10.2, send a POST request by entering the following:
Use cURL to perform the following:
The same can be obtained through a browser using addons such as the REST console.
Use PowerShell to perform the following:
To find out the valid property names for a given function, see the Response Sample in each function definition later in this document.
To read an object, you must construct an HTTP GET request:
https://<IP address>/api/<name space>/<resource locator>/<instance name>
For example, to read switch extension manager information from a VSM with an IP address of 10.10.10.2, send a GET request by entering the following:
Use cURL to perform the following:
Use PowerShell to perform the following:
The above PowerShell command sends the results to the specified output file, which in this case,is "testout.xml" . The default location where the outfile gets saved is the current folder location.
To update an object, you must construct an HTTP POST request:
The request must have a payload that contains JSON-formatted fields that are updated on the object:
For example, to modify the address range for the IP pool named pool1 on a VSM with an IP address of 10.10.10.2, send a POST request by entering the following IP pool:
Use cURL to perform the following:
Use PowerShell to perform the following:
To find the valid property names for a given function, see the Response Sample in each function definition later in this document.