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 contains the following sections:
Using the API Inspector
When you perform a task in the APIC graphical user interface (GUI), the GUI creates and sends internal API messages to the operating system to execute the task. By using the API Inspector, which is a built-in tool of the APIC, you can view and copy these API messages. A network administrator can replicate these messages in order to automate key operations, or you can use the messages as examples to develop external applications that will use the API. .
This example shows two debug messages in the API Inspector window:
13:13:36 DEBUG - method: GET url: http://192.0.20.123/api/class/infraInfra.json response: {"imdata":[{"infraInfra":{"attributes":{"instanceId":"0:0","childAction":"", "dn":"uni/infra","lcOwn":"local","name":"","replTs":"never","status":""}}}]} 13:13:40 DEBUG - method: GET url: http://192.0.20.123/api/class/l3extDomP.json? query-target=subtree&subscription=yes response: {"subscriptionId":"72057598349672459","imdata":[]}
The Managed Object Browser, or Visore, is a utility built into the APIC that provides a graphical view of the managed objects (MOs) using a browser. The Visore utility uses the APIC REST API query methods to browse MOs active in the Application Centric Infrastructure fabric, allowing you to see the query that was used to obtain the information. The Visore utility cannot be used to perform configuration operations.
Note | Only the Firefox, Chrome, and Safari browsers are supported for Visore access. |
The filter form is case sensitive. This area supports all simple APIC REST API query operations.
Name | Description |
---|---|
Class or DN field |
Object class name or fully distinguished name of a managed object. |
Property field |
The property of the managed object on which you want to filter the results. If you leave the Property field empty, the search returns all instances of the specific class. |
Op drop-down list |
Operator for the values of the property on which you want to filter the results. The following are valid operators: |
Val1 field |
The first value for the property on which you want to filter. |
Val2 field |
The second value on which you want to filter. |
The Display XML of last query link displays the full APIC REST API translation of the most recent query run in Visore.
You can bookmark any query results page in your browser to view the results again because the query is encoded in the URL.
Note | Many of the managed objects are only used internally and are not generally applicable to APIC REST API program development. |
Name | Description |
---|---|
Pink background |
Separates individual managed object instances and displays the class name of the object below it. |
Blue or green background |
Indicates the property names of the managed object. |
Yellow or beige background |
Indicates the value of a property name. |
dn property |
Absolute address of each managed object in the object model. |
dn link |
When clicked, displays all managed objects with that dn. |
Class name link |
When clicked, displays all managed objects of that class. |
Left arrow |
When clicked, takes you to the parent object of the managed object. |
Right arrow |
When clicked, takes you to the child objects of the managed object. |
Question mark |
Links you to the XML API documentation for the managed object. |
Step 1 | Enter a class or DN name of the MO in the Class or DN text box. |
Step 2 | (Optional)You can filter the query by entering a property of the MO in the Property text box, an operator in the Op text box, and one or two values in the Val1 and Val2 text boxes. |
Step 3 | Click
Run
Query.
Visore sends a query to the APIC and the requested MO is displayed in a tabular format. |
Step 4 | (Optional)Click the Display URI of last query link to display the API call that executed the query. |
Step 5 | (Optional)Click the Display last response link to display the API response data structure from the query. |
Step 6 | (Optional)In the
dn field of the MO description table, click the
< and
> icons to retrieve the parent and child classes
of the displayed MO.
Clicking > sends a query to the APIC for the children of the MO. Clicking < sends a query for the parent of the MO. |
Step 7 | (Optional)In the dn field of the MO description table, click the additional icons to display statistics, faults, or health information for the MO. |
Testing the API
To test an API request, you can assemble an HTTP message, send it, and inspect the response using a browser add-on utility. RESTful API clients, which are available as add-ons for most popular browsers, provide a user-friendly interface for interacting with the API. Clients include the following:
Browser add-ons pass the session token as a cookie so that there is no need to include the token in the payload data structure.
You can send API messages from a console or a command-line script using cURL, which is a tool for transferring files using URL syntax.
To send a POST message, create a file that contains the JSON or XML command body, and then enter the cURL command in this format:
curl -X POST --data "@<filename>" <URI>
You must specify the name of your descriptor file and the URI of the API operation.
Note | Make sure to include the "@" symbol before the descriptor filename. |
This example creates a new tenant named ExampleCorp using the JSON data structure in the file "newtenant.json":
curl -X POST --data "@newtenant.json" https://192.0.20.123/api/mo/uni/tn-ExampleCorp.json
To send a GET message, enter the cURL command in this format:
curl -X GET <URI>
This example reads information about a tenant in JSON format:
curl -X GET https://192.0.20.123/api/mo/uni/tn-ExampleCorp.json
Note | When testing with cURL, you must log in to the API, store the authentication token, and include the token in subsequent API operations. |
Using the Python requests module, you can send API messages from a Python program.
This example shows you how to log in to the API, store the authentication token, and read a sensor:
import json import requests base_url = 'https://192.0.20.123/api/' # create credentials structure name_pwd = {'aaaUser': {'attributes': {'name': 'georgewa', 'pwd': 'pa55word'}}} json_credentials = json.dumps(name_pwd) # log in to API login_url = base_url + 'aaaLogin.json' post_response = requests.post(login_url, data=json_credentials) # get token from login response structure auth = json.loads(post_response.text) login_attributes = auth['imdata'][0]['aaaLogin']['attributes'] auth_token = login_attributes['token'] # create cookie array from token cookies = {} cookies['APIC-Cookie'] = auth_token # read a sensor, incorporating token in request sensor_url = base_url + 'mo/topology/pod-1/node-1/sys/ch/bslot/board/sensor-3.json' get_response = requests.get(sensor_url, cookies=cookies, verify=False) # display sensor data structure print get_response.json()
In this example, you must manage the authentication token (cookie) for the session. The Python requests module contains a Session() method that manages the token automatically.
For more information about the Python requests module, see http://www.python-requests.org.