Cisco APIC REST API User Guide

Cisco APIC REST API User Guide
First Published: October 31, 2013

Last Modified: September 17, 2014
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version
of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network
topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional
and coincidental.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://
www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (1110R)
© 2013-2014 Cisco Systems, Inc. All rights reserved.

CONTENTS
Preface Preface vii

About This Guide vii
Audience vii
Document Conventions vii
Related Documentation ix
Documentation Feedback x
Obtaining Documentation and Submitting a Service Request x
CHAPTER 1 Overview of the APIC REST API 1

About the Application Policy Infrastructure Controller 1
Management Information Model 1
Object Naming 2
About the APIC REST API 3
CHAPTER 2 Using the APIC REST API 5

Invoking the API 5
Configuring the HTTP Request Method and Content Type 6
Creating the API Command or Query URI 6
Composing the API Command Body 8
Composing the API Command Body for an API Operation on an MO 8
Authenticating and Maintaining an API Session 9
Requiring a Challenge Token for an API Session 11
Filtering API Query Results 12
Applying Query Scoping Filters 12
Composing Query Filter Expressions 14
Sorting and Paginating Query Results 15
Subscribing to Query Results 16

iii
Contents
Creating, Modifying, and Deleting Objects and Properties 18

Using Tags 19
CHAPTER 3 Performing Common Tasks 21

Performing Common Tasks 21
Logging In 22
Example: Using the XML API to Authenticate a User 22
Example: Using the JSON API to Authenticate a User 23
Adding a Tenant 25
Example: Using the XML API to Add a Tenant 25
Example: Using the JSON API to Add a Tenant 26
Adding a User 27
Example: Using the XML API to Add a User 28
Example: Using the JSON API to Add a User 29
Example: Using the JSON API to Add a User with cURL 32
Deploying Endpoint Groups and Contracts for a Three-Tier Application 33
CHAPTER 4 Using Tools for API Development and Testing 37

Using the API Inspector 37
Viewing an API Interchange in the GUI 37
Using the Managed Object Browser 39
Accessing Visore 39
Visore Browser Page 40
Running a Query in Visore 41
Testing the API 42
Testing the API Using Browser Add-Ons 42
Testing the API with cURL 42
Testing the API with Python 43
APPENDIX A Uploading a Device Package File Using the API 45

Uploading a Device Package File Using the API 45
APPENDIX B Additional Examples 47

Information About the API Examples 47
Example: Using the JSON API to Get Top Level System Elements 47

iv
Contents
Example: Using the JSON API to Get Information About a Node 48

Example: Using the JSON API to Get Running Firmware 49
Example: Using the JSON API to Add a Leaf Port Selector Profile 50
APPENDIX C Configuring the Communication Policy 53

Configuring HTTP and HTTPS Using the GUI 53

v
Contents

vi
Preface
This preface includes the following sections:
• About This Guide, page vii

• Audience, page vii
• Document Conventions, page vii
• Related Documentation, page ix
• Documentation Feedback, page x
• Obtaining Documentation and Submitting a Service Request, page x
About This Guide

This guide describes how to compose and send commands and queries to the Application Policy Infrastructure
Controller (APIC) using the APIC REST API. The guide provides examples for a set of common tasks, but
it does not describe how to configure the full feature set of the Cisco Application Centric Infrastructure (ACI)
fabric and it does not list the classes, methods, or data types of the API.
Audience
This guide is intended for software engineers with a background in programming and the use of APIs. Engineers
should have knowledge of XML and JSON, RESTful web service APIs, data systems, networking protocols,
and storage protocols.
Document Conventions
Command descriptions use the following conventions:
Convention Description
bold Bold text indicates the commands and keywords that you enter literally
as shown.

vii
Preface
Document Conventions
Italic Italic text indicates arguments for which the user supplies the values.
[x] Square brackets enclose an optional element (keyword or argument).
[x | y] Square brackets enclosing keywords or arguments separated by a vertical

bar indicate an optional choice.
{x | y} Braces enclosing keywords or arguments separated by a vertical bar

indicate a required choice.
[x {y | z}] Nested set of square brackets or braces indicate optional or required

choices within optional or required elements. Braces and a vertical bar
within square brackets indicate a required choice within an optional
element.
variable Indicates a variable for which you supply values, in context where italics
cannot be used.
string A nonquoted set of characters. Do not use quotation marks around the
string or the string will include the quotation marks.
Examples use the following conventions:
screen font Terminal sessions and information the switch displays are in screen font.
boldface screen font Information you must enter is in boldface screen font.
italic screen font Arguments for which you supply values are in italic screen font.
<> Nonprinting characters, such as passwords, are in angle brackets.
[] Default responses to system prompts are in square brackets.
!, # An exclamation point (!) or a pound sign (#) at the beginning of a line

of code indicates a comment line.
This document uses the following conventions:
Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the
manual.

viii
Preface
Related Documentation
Caution Means reader be careful. In this situation, you might do something that could result in equipment damage
or loss of data.
Warning IMPORTANT SAFETY INSTRUCTIONS

This warning symbol means danger. You are in a situation that could cause bodily injury. Before you
work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with
standard practices for preventing accidents. Use the statement number provided at the end of each warning
to locate its translation in the translated safety warnings that accompanied this device.
SAVE THESE INSTRUCTIONS
Related Documentation
For detailed reference information about API classes, properties, and data types, see the Cisco APIC
Management Information Model Reference, which is a web-based application.
You can find detailed procedures of many common tasks using the API in the Cisco APIC Getting Started
Guide.
Web-Based Documentation
• Cisco APIC Management Information Model Reference
• Cisco APIC Online Help Reference
• Cisco ACI MIB Support List
Downloadable Documentation
• Cisco Application Centric Infrastructure Release Notes
• Cisco Application Centric Infrastructure Fundamentals Guide
• Cisco APIC Getting Started Guide
• Cisco APIC REST API User Guide
• Cisco APIC Command Line Interface User Guide
• Cisco APIC Faults, Events, and System Message Guide
• Cisco APIC Layer 4 to Layer 7 Device Package Development Guide
• Cisco APIC Layer 4 to Layer 7 Services Deployment Guide
• Cisco ACI Firmware Management Guide
• Cisco ACI Troubleshooting Guide
• Cisco ACI NX-OS Syslog Reference Guide
• Cisco ACI Switch Command Reference, NX-OS Release 11.0

ix
Preface
Documentation Feedback
• Cisco ACI MIB Quick Reference

• Cisco Nexus CLI to Cisco APIC Mapping Guide
• Installing the Cisco Application Virtual Switch with the Cisco APIC
• Configuring the Cisco Application Virtual Switch using the Cisco APIC
• Application Centric Infrastructure Fabric Hardware Installation Guide
Documentation Feedback
To provide technical feedback on this document, or to report an error or omission, please send your comments
to apic-docfeedback@cisco.com. We appreciate your feedback.
Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service
request, and gathering additional information, see What's New in Cisco Product Documentation, at: http://
www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.
Subscribe to What's New in Cisco Product Documentation, which lists all new and revised Cisco technical
documentation, as an RSS feed and deliver content directly to your desktop using a reader application. The
RSS feeds are a free service.

x
CHAPTER 1
Overview of the APIC REST API
This chapter contains the following sections:
• About the Application Policy Infrastructure Controller, page 1

• Management Information Model , page 1
• Object Naming, page 2
• About the APIC REST API, page 3
About the Application Policy Infrastructure Controller

The Cisco Application Centric Infrastructure (ACI) is a distributed, scalable, multitenant infrastructure with
external end-point connectivity controlled and grouped through application-centric policies. The Application
Policy Infrastructure Controller (APIC) is the unified point of automation, management, monitoring, and
programmability for the ACI. The APIC supports the deployment, management, and monitoring of any
application anywhere, with a unified operations model for physical and virtual components of the infrastructure.
The APIC programmatically automates network provisioning and control that is based on the application
requirements and policies. It is the central control engine for the broader cloud network; it simplifies
management and allows flexibility in how application networks are defined and automated. It also provides
northbound Representational State Transfer (REST) APIs. The APIC is a distributed system that is implemented
as a cluster of many controller instances.
Management Information Model

All the physical and logical components that comprise the Application Centric Infrastructure fabric are
represented in a hierarchical management information model (MIM), also referred to as the management
information tree (MIT). Each node in the tree represents a managed object (MO) or group of objects that
contains its administrative state and its operational state.
The hierarchical structure starts at the top (Root) and contains parent and child nodes. Each node in this tree
is an MO and each object in the ACI fabric has a unique distinguished name (DN) that describes the object
and its place in the tree. MOs are abstractions of the fabric resources. An MO can represent a physical object,
such as a switch or adapter, or a logical object, such as a policy or fault.

1
Object Naming
Configuration policies are the majority of the policies in the system and describe the configurations of different
ACI fabric components. Policies determine how the system behaves under specific circumstances. Certain
MOs are not created by users but are automatically created by the fabric (for example, power supply objects
and fan objects). By invoking the API, you are reading and writing objects to the MIM.
The information model is centrally stored as a logical model by the APIC, while each switch node contains
a complete copy as a concrete model. When a user creates a policy in the APIC that represents a configuration,
the APIC updates the logical model. The APIC then performs the intermediate step of creating a fully elaborated
policy from the user policy and pushes the policy into all the switch nodes where the concrete model is updated.
The models are managed by multiple data management engine (DME) processes that run in the fabric. When
a user or process initiates an administrative change to a fabric component (for example, when you apply a
profile to a switch), the DME first applies that change to the information model and then applies the change
to the actual managed endpoint. This approach is called a model-driven framework.
The following branch diagram of a leaf switch port starts at the topRoot of the ACI fabric MIT and shows a
hierarchy that comprises a chassis with two line module slots, with a line module in slot 2.
|——root———————————–– (root)
|——sys———————————––– (sys)
|——ch————————————————(sys/ch)
|——lcslot-1——————————(sys/ch/lcslot-1)
|——lcslot-2——————————(sys/ch/lcslot-2)
|——lc————————————————(sys/ch/lcslot-2/lc)
|——leafport-1————————(sys/ch/lcslot-2/lc/leafport-1)
Object Naming
You can identify a specific object by its distinguished name (DN) or by its relative name (RN).
Distinguished Name
The DN enables you to unambiguously identify a specific target object. The DN consists of a series of RNs:
dn = {rn}/{rn}/{rn}/{rn}...
In this example, the DN provides a fully qualified path for fabport-1 from the top of the object tree to the
object. The DN specifies the exact managed object on which the API call is operating.
< dn =”sys/ch/lcslot-1/lc/fabport-1” />
Relative Name
The RN identifies an object from its siblings within the context of its parent object. The DN contains a sequence
of RNs.
For example, this DN:
<dn = "sys/ch/lcslot-1/lc/fabport-1"/>
contains these RNs:
Relative Name Class Description

sys top:System Top level of this system

2
About the APIC REST API
Relative Name Class Description

ch eqpt:Ch Hardware chassis container
lcslot-1 eqpt:LCSlot Line module slot 1
lc eqpt:LC Line (I/O) module
fabport-1 eqpt:FabP Fabric-facing external I/O port 1

The APIC REST API is a programmatic interface to the Application Policy Infrastructure Controller (APIC)
that uses a Representational State Transfer (REST) architecture. The API accepts and returns HTTP or HTTPS
messages that contain JavaScript Object Notation (JSON) or Extensible Markup Language (XML) documents.
You can use any programming language to generate the messages and the JSON or XML documents that
contain the API methods or managed object (MO) descriptions.
The API model provides major functionality for application development. Configuration and state information
of the Cisco Application Centric Infrastructure (ACI) fabric is stored in a hierarchical tree structure known
as the management information tree (MIT), which is accessible through the API. You can make changes on
a single object or an object subtree. With an API call, you can make changes to the configuration of switches,
adapters, policies, and other hardware and software components.
The API operates in forgiving mode, which means that missing attributes are substituted with default values
(if applicable) that are maintained in the internal data management engine (DME). The DME validates and
rejects incorrect attributes. The API is also atomic. If multiple MOs are being configured (for example, virtual
NICs), and any of the MOs cannot be configured, the API stops its operation. It returns the configuration to
its prior state, stops the API operation that listens for API requests, and returns an error code.
Updates to MOs and properties conform to the existing object model, which ensures backward compatibility.
If existing properties are changed during a product upgrade, they are managed during the database load after
the upgrade. New properties are assigned default values.
Full event subscription is enabled. When any MO is created, changed, or deleted because of a user- or
system-initiated action, an event is generated. With an API query, you can create a subscription to any future
changes in the results of that query.
Operation of the API is transactional and terminates on a single data model. The APIC is responsible for all
endpoint communication, such as state updates; users cannot communicate directly to endpoints. In this way,
developers are relieved from the task of administering isolated, individual component configurations.
The API model includes these programmatic entities:
• Classes—Templates that define the properties and states of objects in the management information tree.
• Methods—Actions that the API performs on one or more objects.
• Types—Object properties that map values to the object state (for example, equipmentPresence).
A typical request comes into the DME and is placed in the transactor queue in first in, first out (FIFO) order.
The transactor gets the request from the queue, interprets the request, and performs an authorization check.
After the request is confirmed, the transactor updates the MIT. This complete operation is done in a single
transaction.

3
Note For detailed reference information about API classes, properties, and data types, see the Cisco APIC
Management Information Model Reference, which is a web-based application.

4
CHAPTER 2
Using the APIC REST API
Note For security, only HTTPS is enabled as the default mode for API communications. HTTP and
HTTP-to-HTTPS redirection can be enabled if desired, but are less secure. For simplicity, this document
refers to HTTP in descriptions of protocol components and interactions.
• Invoking the API, page 5

• Configuring the HTTP Request Method and Content Type, page 6
• Creating the API Command or Query URI, page 6
• Composing the API Command Body, page 8
• Authenticating and Maintaining an API Session, page 9
• Filtering API Query Results, page 12
• Sorting and Paginating Query Results, page 15
• Subscribing to Query Results, page 16
• Creating, Modifying, and Deleting Objects and Properties, page 18
• Using Tags, page 19
Invoking the API

You can invoke an API function by sending an HTTP/1.1 or HTTPS POST, GET, or DELETE message to
the Application Policy Infrastructure Controller (APIC). The HTML body of the POST message contains a
Javascript Object Notation (JSON) or XML data structure that describes an MO or an API method. The HTML
body of the response message contains a JSON or XML structure that contains requested data, confirmation
of a requested action, or error information.

5
Configuring the HTTP Request Method and Content Type
Note The root element of the response structure is imdata. This element is merely a container for the response;
it is not a class in the management information model (MIM).
Configuring the HTTP Request Method and Content Type

API commands and queries must use the supported HTTP or HTTPS request methods and header fields, as
described in the following sections.
Note For security, only HTTPS is enabled as the default mode for API communications. HTTP and
HTTP-to-HTTPS redirection can be enabled if desired, but are less secure. For simplicity, this document
refers to HTTP in descriptions of protocol components and interactions.
Request Methods
The API supports HTTP POST, GET, and DELETE request methods as follows:
• An API command to create or update an MO, or to execute a method, is sent as an HTTP POST message.
• An API query to read the properties and status of an MO, or to discover objects, is sent as an HTTP
GET message.
• An API command to delete an MO is sent as either an HTTP POST or DELETE message. In most cases,
you can delete an MO by setting its status to deleted in a POST operation.
Other HTTP methods, such as PUT, are not supported.
Note Although the DELETE method is supported, the HTTP header might show only these:
Access-Control-Allow-Methods:POST,GET,OPTIONS
Content Type
The API supports either JSON or XML data structures in the HTML body of an API request or response. You
must specify the content type by terminating the URI pathname with a suffix of either .json or .xml to indicate
the format to be used. The HTTP Content-Type and Accept headers are ignored by the API.
Creating the API Command or Query URI

You can invoke an API command or query by sending an HTTP or HTTPS message to the APIC with a
uniform resource identifier (URI) of this form for an operation on a managed object (MO):
{http| https}://host[ :port ]/api/mo/dn.{json| xml}[?options]
Use this form for an operation on an object class:

6
Creating the API Command or Query URI
{http| https}://host[ :port ]/api/class/className.{json| xml}[?options]
This example shows a URI for an API operation that involves an MO of class fv:Tenant:
https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml
URI Components
The components of the URI are as follows:
• http:// or https://—Specifies HTTP or HTTPS. By default, only HTTPS is enabled. HTTP or
HTTP-to-HTTPS redirection, if desired, must be explicitly enabled and configured, as described in
Configuring HTTP and HTTPS Using the GUI, on page 53. HTTP and HTTPS can coexist.
• host—Specifies the hostname or IP address of the APIC.
• :port—Specifies the port number for communicating with the APIC. If your system uses standard port
numbers for HTTP (80) or HTTPS (443), you can omit this component.
• /api/—Specifies that the message is directed to the API.
• mo | class—Specifies whether the target of the operation is an MO or an object class.
• dn—Specifies the distinguished name (DN) of the targeted MO.
• className—Specifies the name of the targeted class. This name is a concatenation of the package name
of the object queried and the name of the class queried in the context of the corresponding package.
For example, the class aaa:User results in a className of aaaUser in the URI.
• json | xml—Specifies whether the encoding format of the command or response HTML body is JSON
or XML.
• ?options—(Optional) Specifies one or more filters, selectors, or modifiers to a query. Multiple option
statements are joined by an ampersand (&).
The URI for an API Operation on an MO

In an API operation to create, read, update, or delete a specific MO, the resource path consists of /mo/ followed
by the DN of the MO as described in the Cisco APIC Management Information Model Reference. For example,
the DN of a tenant object, as described in the reference definition of class fv:Tenant, is uni/tn-[name]. This
URI specifies an operation on an fv:Tenant object named ExampleCorp:
https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml
Alternatively, in a POST operation, you can POST to /api/mo and provide the DN in the body of the message,
as in this example:
POST https://192.0.20.123/api/mo.xml
<fvTenant dn="uni/tn-ExampleCorp"/>
You can also provide only the name in the message body and POST to /api/mo and the remaining relative
name components, as in this example:
POST https://192.0.20.123/api/mo/uni.xml

7
Composing the API Command Body
<fvTenant name="ExampleCorp"/>
The URI for an API Operation on a Node MO

In an API operation to access an MO on a specific node device in the fabric, the resource path consists of
/mo/topology/pod-number/node-number/sys/ followed by the node component. For example, to access a
board sensor in chassis slot b of node-1 in pod-1, use this URI:
GET https://192.0.20.123/api/mo/topology/pod-1/node-1/sys/ch/bslot/board/sensor-3.json
The URI for an API Operation on a Class

In an API operation to get information about a class, the resource path consists of /class/ followed by the
name of the class as described in the Cisco APIC Management Information Model Reference. In the URI, the
colon in the class name is removed. For example, this URI specifies a query on the class aaa:User:
GET https://192.0.20.123/api/class/aaaUser.json
Composing the API Command Body

The HTML body of a POST operation must contain a JSON or XML data structure that provides the essential
information necessary to execute the command. No data structure is sent with a GET or DELETE operation.
Guidelines for Composing the API Command Body

• The data structure does not need to represent the entire set of attributes and elements of the target MO
or method, but it must provide at least the minimum set of properties or parameters necessary to identify
the MO and to execute the command, not including properties or parameters that are incorporated into
the URI.
• In the data structure, the colon after the package name is omitted from class names and method names.
For example, in the data structure for an MO of class zzz:Object, label the class element as zzzObject.
• If an XML data structure contains no children or subtrees, the object element can be self-closing.
• The API is case sensitive.
• When sending an API command, with 'api' in the URL, the maximum size of the HTML body for the
API POST command is 1 MB.
• When uploading a device package file, with 'ppi' in the URL, the maximum size of the HTML body for
the POST command is 10 MB.
Composing the API Command Body for an API Operation on an MO

To compose a command to create, modify, or delete an MO, create a JSON or XML data structure that describes
the essential properties and children of the object's class by using the class description in the Cisco APIC
Management Information Model Reference. You can omit any attributes or children that are not essential to
execute the command.

8
Authenticating and Maintaining an API Session
A JSON structure for an MO of hypothetical class zzz:Object resembles this structure:
{
"zzzObject" : {
"attributes" : {
"property1" : "value1",
"property2" : "value2",
"property3" : "value3"
},
"children" :
[{
"zzzChild1" : {
"attributes" : {
"childProperty1" : "childValue1",
"childProperty2" : "childValue1"
},
"children" : []
}
}
]
}
}
An XML structure for an MO of hypothetical class zzz:Object resembles this structure:
<zzzObject
property1 = "value1",
property2 = "value2",
property3 = "value3">
<zzzChild1
childProperty1 = "childValue1",
childProperty2 = "childValue1">
</zzzChild1>
</zzzObject>
A successful operation returns a complete data structure for the MO.

Before you can access the API, you must first log in with the name and password of a configured user.
When a login message is accepted, the API returns a data structure that includes a session timeout period in
seconds and a token that represents the session. The token is also returned as a cookie in the HTTP response
header. To maintain your session, you must send login refresh messages to the API if no other messages are
sent for a period longer than the session timeout period. The token changes each time that the session is
refreshed.
Note The default session timeout period is 300 seconds or 5 minutes.
These API methods enable you to manage session authentication:

• aaaLogin—Sent as a POST message, this method logs in a user and opens a session. The message body
contains an aaa:User object with the name and password attributes, and the response contains a session
token and cookie. If multiple AAA login domains are configured, you must prepend the user's name
with apic:domain\\.

9
• aaaRefresh—Sent as a GET message with no message body or as a POST message with the aaaLogin
message body, this method resets the session timer. The response contains a new session token and
cookie.
• aaaLogout—Sent as a POST message, this method logs out the user and closes the session. The message
body contains an aaa:User object with the name attribute. The response contains an empty data structure.
• aaaListDomains—Sent as a GET message, this method returns a list of valid AAA login domains. You
can send this message without logging in.
You can call the authentication methods using this syntax, specifying either JSON or XML data structures:
{http| https}://host[ :port ]/api/methodName.{json| xml}
This example shows a user login message that uses a JSON data structure:
POST https://192.0.20.123/api/aaaLogin.json
{
"aaaUser" : {
"attributes" : {
"name" : "georgewa",
"pwd" : "paSSword1"
}
}
}
This example shows part of the response upon a successful login, including the token and the refresh timeout
period:
RESPONSE:
{
"imdata" : [{
"aaaLogin" : {
"attributes" : {
"token" :
"GkZl5NLRZJl5+jqChouaZ9CYjgE58W/pMccR+LeXmdO0obG9NB
Iwo1VBo7+YC1oiJL9mS6I9qh62BkX+Xddhe0JYrTmSG4JcKZ4t3
bcP2Mxy3VBmgoJjwZ76ZOuf9V9AD6Xl83lyoR4bLBzqbSSU1R2N
IgUotCGWjZt5JX6CJF0=",
"refreshTimeoutSeconds" : "300",
"lastName" : "Washington",
"firstName" : "George"
},
"children" : [{
...
[TRUNCATED]
...
}
In the preceding example, the refreshTimeoutSeconds attribute indicates that the session timeout period is
300 seconds.
This example shows how to request a list of valid login domains:
GET https://192.0.20.123/api/aaaListDomains.json
RESPONSE:
{
"imdata": [{
"name": "ExampleRadius"
},
{
"name": "local",

10
Requiring a Challenge Token for an API Session
"guiBanner": "San Jose Fabric"

}]
}
In the preceding example, the response data shows two possible login domains, 'ExampleRadius' and 'local.'
The following example shows a user login message for the ExampleRadius login domain:
{
"aaaUser" : {
"attributes" : {
"name" : "apic:ExampleRadius\\georgewa",
"pwd" : "paSSword1"
}
}
}
Related Topics
Example: Using the JSON API to Authenticate a User, on page 23
Example: Using the XML API to Authenticate a User, on page 22
Requiring a Challenge Token for an API Session

For stronger API session security, you can require your session to use a challenge token. When you request
this feature during login, the API returns a token string that you must include in every subsequent message
to the API. Unlike the normal session token, the challenge token is not stored as a cookie to be automatically
provided by your browser. Your API commands and queries must provide the challenge token using one of
the following methods:
• The challenge token is sent as a 'url-token' parameter in the URI of your API message.
• The challenge token is part of the HTTP or HTTPS header using 'APIC-challenge'.
To initiate a session that requires a challenge token, include the URI parameter statement
?gui-token-request=yes in your login message, as shown in this example:
POST https://192.0.20.123/api/aaaLogin.json?gui-token-request=yes
The response message body contains an attribute of the form "urlToken":"token", where token is a long
string of characters representing the challenge token. All subsequent messages to the API during this session
must include the challenge token, as shown in this example where it is sent as a 'url-token' URI parameter:
GET https://192.0.20.123/api/class/aaaUser.json?url-token=fa47e44df54562c24fef6601dc...
This example shows how the challenge token is sent as an 'APIC-challenge' field in the HTTP header:
GET //api/class/aaaUser.json
HTTP/1.1
Host: 192.0.20.123
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml,application/json
APIC-challenge: fa47e44df54562c24fef6601dcff72259299a077336aecfc5b012b036797ab0f
.
.
.

11
Filtering API Query Results
Filtering API Query Results

You can filter the results of an API query by appending one or more condition statements to the query URI
as a parameter in this format:
https://URI?condition[&condition[&...]]
Multiple condition statements are joined by an ampersand (&).
Note The condition statement must not contain spaces.
Options are available to filter by object attributes and object subtrees.
Applying Query Scoping Filters

You can limit the scope of the response to an API query by applying scoping filters. You can limit the scope
to the first level of an object or to one or more of its subtrees or children based on the class, properties,
categories, or qualification by a logical filter expression.
query-target={self | children | subtree}

This statement restricts the scope of the query. This list describes the available scopes:
• self—(Default) Considers only the MO itself, not the children or subtrees.
• children—Considers only the children of the MO, not the MO itself.
• subtree—Considers the MO itself and its subtrees.
target-subtree-class=mo-class1[,mo-class2]...
This statement specifies which object classes are to be considered when the query-target option is used with
a scope other than self. You can specify multiple desired object types as a comma-separated list with no spaces.
To request subtree information, combine query-target=subtree with the target-subtree-class statement to
indicate the specific subtree as follows:
query-target=subtree&target-subtree-class=className
This example requests information about the running firmware. The information is contained in the
firmware:IfcRunning subtree (child) object of the APIC firmware status container firmware:IfcFwStatusCont:
GET https://192.0.20.123/api/class/firmwareIfcFwStatusCont.json?
query-target=subtree&target-subtree-class=firmwareIfcRunning
query-target-filter=filter-expression
This statement specifies a logical filter to be applied to the response. This statement can be used by itself or
applied after the query-target statement.

12
Applying Query Scoping Filters
rsp-subtree={no | children | full}

For objects returned, this option specifies whether child objects are included in the response. This list describes
the available choices:
• no—(Default) Response includes no children.
• children—Response includes only the children.
• full—Response includes the entire structure including the children.
rsp-subtree-class=mo-class
When child objects are to be returned, this statement specifies that only child objects of the specified object
class are included in the response.
rsp-subtree-filter=filter-expression
When child objects are to be returned, this statement specifies a logical filter to be applied to the child objects.
rsp-subtree-include=category1[,category2...][option]
When child objects are to be returned, this statement specifies additional contained objects or options to be
included in the response. You can specify one or more of the following categories in a comma-separated list
with no spaces:
• audit-logs—Response includes subtrees with the history of user modifications to managed objects.
• event-logs—Response includes subtrees with event history information.
• faults—Response includes subtrees with currently active faults.
• fault-records—Response includes subtrees with fault history information.
• health—Response includes subtrees with current health information.
• health-records—Response includes subtrees with health history information.
• relations—Response includes relations-related subtree information.
• stats—Response includes statistics-related subtree information.
• tasks—Response includes task-related subtree information.
With any of the preceding categories, you can also specify one of the following options to further refine the
query results:
• count—Response includes a count of matching subtrees but not the subtrees themselves.
• no-scoped—Response includes only the requested subtree information. Other top-level information of
the target MO is not included in the response.
• required—Response includes only the managed objects that have subtrees matching the specified
category.

13
Composing Query Filter Expressions
For example, to include fault-related subtrees, specify fault in the list. To return only fault-related subtrees
and no other top-level MO information, specify fault,no-scoped in the list as shown in this example:
query-target=subtree&rsp-subtree-include=fault,no-scoped
Related Topics
Composing Query Filter Expressions, on page 14
Example: Using the JSON API to Get Running Firmware, on page 49
Composing Query Filter Expressions

You can filter the response to an API query by applying an expression of logical operators and values.
A basic equality or inequality test is expressed as follows:
query-target-filter=[eq|ne](attribute,value)
You can create a more complex test by combining operators and conditions using parentheses and commas:
query-target-filter=[and|or]([eq|ne](attribute,value),[eq|ne](attribute,value),...)
Available Logical Operators

This table lists the available logical operators for query filter expressions.
Operator Description
eq Equal to
ne Not equal to
lt Less than
gt Greater than
le Less than or equal to
ge Greater than or equal to
bw Between
not Logical inverse
and Logical AND
or Logical OR
xor Logical exclusive OR
true Boolean TRUE

14
Sorting and Paginating Query Results
Operator Description
false Boolean FALSE
anybit TRUE if at least one bit is set
allbits TRUE if all bits are set
wcard Wildcard
pholder Property holder
passive Passive holder
Examples
This example returns all managed objects of class aaaUser whose last name is equal to "Washington":
GET https://192.0.20.123/api/class/aaaUser.json?
query-target-filter=eq(aaaUser.lastName,"Washington")
This example returns endpoint groups whose fabEncap property is "vxlan-12780288":
GET https://192.0.20.123/api/class/fvAEPg.xml?
query-target-filter=eq(fvAEPg.fabEncap,"vxlan-12780288")
This example shows all tenant objects with a current health score of less than 50:
GET https://192.0.20.123/api/class/fvTenant.json?
rsp-subtree-include=health,required
&
rsp-subtree-filter=lt(healthInst.cur,"50")
This example returns all endpoint groups and their faults under the tenant ExampleCorp:
GET https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml?
query-target=subtree
&
target-subtree-class=fvAEPg
&
rsp-subtree-include=faults
This example returns aaa:Domain objects whose names are not "infra" or "common":
GET https://192.0.20.123/api/class/aaaDomain.json?
query-target-filter=
and(ne(aaaDomain.name,"infra"),
ne(aaaDomain.name,"common"))
Sorting and Paginating Query Results

When sending an API query that returns a large quantity of data, you can have the return data sorted and
paginated to make it easier to find the information you need.

15
Subscribing to Query Results
Sorting the Results

By adding the order-by operator to the query URI, you can sort the query response by one or more properties
of a class, and you can specify the direction of the order using the following syntax.
order-by=classname.property[|{asc| desc}][,classname.property[|{asc| desc}]][,...]
Use the optional pipe delimiter ('|') to specify either ascending order (asc) or descending order (desc). If no
order is specified, the default is ascending order.
You can perform a multi-level sort by more than one property (for example, last name and first name), but
all properties must be of the same MO or they must be inherited from the same abstract class.
This example shows you how to sort users by last name, then by first name:
GET
https://192.0.20.123/api/class/aaaUser.json?order-by=aaaUser.lastName|asc,aaaUser.firstName|asc
Paginating the Results

By adding the page-size operator to the query URI, you can divide the query results into groups (pages) of
objects using the following syntax. The operand specifies the number of objects in each group.
page-size=number-of-objects-per-page
By adding the page operator in the query URI, you can specify a single group to be returned using the following
syntax. The pages start from number 0.
page=page-number
This example shows you how to specify 15 fault instances per page in descending order, returning only the
first page:
GET
https://192.0.20.123/api/class/faultInfo.json?order-by=faultInst.severity|desc&page=0&page-size=15
Note Every query, whether paged or not, generates a new set of results. When you perform a query that returns
only a single page, the query response includes a count of the total results, but the unsent pages are not
stored and cannot be retrieved by a subsequent query. A subsequent query generates a new set of results
and returns the page requested in that query.

When you perform an API query, you have the option to create a subscription to any future changes in the
results of that query that occur during your active API session. When any MO is created, changed, or deleted
because of a user- or system-initiated action, an event is generated. If that event changes the results of an
active subscribed query, the APIC generates a push notification to the API client that created the subscription.

16
Opening a WebSocket
The API subscription feature uses the WebSocket protocol (RFC 6455) to implement a two-way connection
with the API client through which the API can send unsolicited notification messages to the client. To establish
this notification channel, you must first open a WebSocket connection with the API. Only a single WebSocket
connection is needed to support multiple query subscriptions with multiple APIC instances. The WebSocket
connection is dependent on your API session connection, and closes when your API session ends.
The WebSocket connection is typically opened by a JavaScript method in an HTML5-compliant browser, as
in the following example:
var Socket = new WebSocket(https://192.0.20.123/socket%TOKEN%);
In the URI, the %TOKEN% is the current API session token (cookie). This example shows the URI with a
token:
https://192.0.20.123/socketGkZl5NLRZJl5+jqChouaZ9CYjgE58W/pMccR+LeXmdO0obG9NB
Iwo1VBo7+YC1oiJL9mS6I9qh62BkX+Xddhe0JYrTmSG4JcKZ4t3bcP2Mxy3VBmgoJjwZ76ZOuf9V9AD6X
l83lyoR4bLBzqbSSU1R2NIgUotCGWjZt5JX6CJF0=
After the WebSocket connection is established, it is not necessary to resend the API session token when the
API session is refreshed.
Creating a Subscription
To create a subscription to a query, perform the query with the option ?subscription=yes. This example
creates a subscription to a query of the fv:Tenant class in the JSON format:
GET https://192.0.20.123/api/class/fvTenant.json?subscription=yes
The query response contains a subscription identifier, subscriptionId, that you can use to refresh the
subscription and to identify future notifications from this subscription.
{
"subscriptionId" : "72057611234574337",
"imdata" : [{
"fvTenant" : {
"attributes" : {
"instanceId" : "0:0",
"childAction" : "",
"dn" : "uni/tn-common",
"lcOwn" : "local",
"monPolDn" : "",
"name" : "common",
"replTs" : "never",
"status" : ""
}
}
}
]
}
Receiving Notifications
An event notification from the subscription delivers a data structure that contains the subscription ID and the
MO description. In this JSON example, a new user has been created with the name "sysadmin5":
{
"subscriptionId" : ["72057598349672454", "72057598349672456"],
"imdata" : [{
"aaaUser" : {

17
Creating, Modifying, and Deleting Objects and Properties
"attributes" : {
"accountStatus" : "active",
"childAction" : "",
"clearPwdHistory" : "no",
"descr" : "",
"dn" : "uni/userext/user-sysadmin5",
"email" : "",
"encPwd" : "TUxISkhH$VHyidGgBX0r7N/srt/YcMYTEn5248ommFhNFzZghvAU=",
"expiration" : "never",
"expires" : "no",
"firstName" : "",
"intId" : "none",
"lastName" : "",
"lcOwn" : "local",
"name" : "sysadmin5",
"phone" : "",
"pwd" : "",
"pwdLifeTime" : "no-password-expire",
"pwdSet" : "yes",
"replTs" : "2013-05-30T11:28:33.835",
"rn" : "",
"status" : "created"
}
}
}
]
}
Because multiple active subscriptions can exist for a query, a notification can contain multiple subscription
IDs as in the example shown.
Note Notifications are supported in either JSON or XML format.
Refreshing the Subscription

To continue to receive event notifications, you must periodically refresh each subscription during your API
session. To refresh a subscription, send an HTTP GET message to the API method subscriptionRefresh with
the parameter id equal to the subscriptionId as in this example:
GET https://192.0.20.123/api/subscriptionRefresh.json?id=72057611234574337
The API returns an empty response to the refresh message unless the subscription has expired.
Note The timeout period for a subscription is one minute. To prevent lost notifications, you must send a
subscription refresh message at least once every 60 seconds.
Creating, Modifying, and Deleting Objects and Properties

Before performing an API operation on a managed object (MO) or its properties, you should view the object's
class definition in the Cisco APIC Management Information Model Reference, which is a web-based document.
The Management Information Model (MIM) serves as a schema that defines rules such as the following:
• the classes of parent objects to which an MO can be attached
• the classes of child objects that can be attached to an MO

18
Using Tags
• the number of child objects of a class type that can be attached to an MO

• whether a user can create, modify, or delete an MO, and the privilege level required to do so
• the properties (attributes) of an object class
• the data type and range of a property
When you send an API command, the APIC checks the command for conformance with the MIM schema. If
an API command violates the MIM schema, the APIC rejects the command and returns an error message. For
example, you can create an MO only if it is allowed in the path you have specified in the command URI and
only if you have the required privilege level for that object class. You can configure an MO's properties only
with valid data, and you cannot create properties.
When composing an API command to create an MO, you need only include enough information in the
command's URI and data structure to uniquely define the new MO. If you omit the configuration of a property
when creating the MO, the property is populated with a default value if the MIM specifies one, or it is left
blank.
When modifying a property of an MO, you need only specify the property to be modified and its new value.
Other properties will be left unchanged.
Note When you modify an MO that affects APIC or switch management communication policy, you might
experience a brief disruption of any operations in progress on any APIC or switch web interface in the
fabric. Configuration changes that can result in disruption include the following:
• changing management port settings, such as port number
• enabling or disabling HTTPS
• changing the state of redirection to HTTPS
• PKI changes, such as key ring
Tip In addition to the API examples shown in this document, you can find detailed examples of many common
tasks using the API in the Cisco APIC Getting Started Guide.
Using Tags
To simplify API operations, you can assign tags to an object. A tag allows you to group multiple objects by
a descriptive name. You can assign the same tag name to multiple objects and you can assign one or more tag
names to an object. In an API operation, you can refer to the object or group of objects by the tag name instead
of by the distinguished name (DN).
Adding Tags
You can add one or more tags by using the following syntax in the URI of an API POST operation:
/api/tag/mo/dn.{json| xml}?add=[ , name, ... ][, name, ...]

19
Using Tags
In this syntax, name is the name of a tag and dn is the distinguished name of the object to which the tag is
assigned.
This example shows how to assign the tags tenants and orgs to the tenant named ExampleCorp:
POST https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml?add=tenants,orgs
Removing Tags
You can remove one or more tags by using the following syntax in the URI of an API POST operation:
/api/tag/mo/dn.{json| xml}?remove=name[ , name, ... ]
This example shows how to remove the tag orgs from the tenant named ExampleCorp:
POST https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml?remove=orgs
You can delete all instances of a tag by using the following syntax in the URI of an API DELETE operation:
/api//tag/name.{json| xml}
This example shows how to remove the tag orgs from all objects:
DELETE https://192.0.20.123/api/tag/orgs.xml
Additional Examples of Using Tags
Note In the examples in this section, the responses have been edited to remove attributes unrelated to tags.
This example shows how to find all tags assigned to the tenant named ExampleCorp:
GET https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml
RESPONSE:
<imdata>
<tagInst
dn="uni/tn-ExampleCorp/tag-tenants"
name="tenants"
/>
<tagInst
dn="uni/tn-ExampleCorp/tag-orgs"
name="orgs"
/>
</imdata>
This example shows how to find all objects with the tag 'tenants':
GET https://192.0.20.123/api/tag/tenants.xml
RESPONSE:
<imdata>
<fvTenant
dn="uni/tn-ExampleCorp"
name="ExampleCorp"
/>
</imdata>

20
CHAPTER 3
Performing Common Tasks
• Performing Common Tasks, page 21

• Logging In, page 22
• Adding a Tenant, page 25
• Adding a User, page 27
• Deploying Endpoint Groups and Contracts for a Three-Tier Application, page 33
Note You can find detailed procedures of many common tasks using the API in the Cisco APIC Getting Started
Guide.
This section provides simple examples of typical tasks that are required in order to create a tenant and deploy
an application. These are the general steps:
• Logging in—Open a session to perform configuration tasks.
• Creating a tenant—Create a private domain within the fabric for a tenant company who will host an
application.
• Creating a user—Create an account for the tenant's administrator, who will deploy and maintain the
tenant's application.
• Deploying an application—Configure the endpoint groups and contracts in a tenant network to connect
the servers needed to host an application.
Note In the examples, the JSON and XML structures have been expanded with line feeds, spaces, and indentations
for readability.

21
Logging In
Logging In
You can log in to the APIC REST API by sending a valid username and password in a data structure to the
aaaLogin API method, as described in Authenticating and Maintaining an API Session, on page 9. Following
a successful login, you must periodically refresh the session.
The following examples show how to log in as an administrator, refresh the session during configuration, and
log out using XML and JSON.
Example: Using the XML API to Authenticate a User

This example logs in a user by using an XML data structure that contains the username and password:
POST https://192.0.20.123/api/aaaLogin.xml
<aaaUser name="georgewa" pwd="paSSword1"/>
This example shows the response upon a successful login:
<imdata>
<aaaLogin
token=
"mk/i+LHZMhFQ47YyMlfZOjmUQQV4PXwFAY/6Dyg5Bm7PC0SVdm
MVWeOlLw69AoNoRVziR8GQeNqPbX/Vu92PxWyPjGx7kOQpoTaUY
P4Y2NkBwRfl5fEDwUe5WnGl3VoBXF4nrc8QSG8N1UWCuIFIyt9O
OzgsLG58fTf4OPCUqQL="
refreshTimeoutSeconds="300" lastName="Washington" firstName="George">
<aaaUserDomain name="all" rolesR="0" rolesW="2">
<aaaReadRoles/>
<aaaWriteRoles>
<role name="admin"/>
</aaaWriteRoles>
</aaaUserDomain>
<aaaUserDomain name="common" rolesR="0" rolesW="1">
<aaaReadRoles/>
<aaaWriteRoles>
<role name="read-only"/>
</aaaWriteRoles>
</aaaUserDomain>
<DnDomainMapEntry dn="uni/tn-common" readPrivileges="0" writePrivileges="3"/>
</aaaLogin>
</imdata>
The response contains a session timeout period and a session token, along with domain and role information
about the user.
This example refreshes the session using the aaaRefresh API method:
GET https://192.0.20.123/api/aaaRefresh.xml
This example shows the response upon a successful session refresh:
<?xml version="1.0" encoding="UTF-8"?>

<imdata>
<aaaLogin
token=
"mk/i+LHZMhFQ47YyMlfZOua51veZ5mdbJAbHG7vjKVJ7QAuUDW
YGGkAdwSxjjcPYK/4Hav3QdZN/E7zJ/Rhc87tmpihVWpkP42VqU
D4aeELVQULz97ZpKnGfF0ki9vqBYkCYRg0vMstXO8IhxNYLtlC8
rxzgZFti+6biMQ+boRx="
refreshTimeoutSeconds="0"

22
Example: Using the JSON API to Authenticate a User
lastName=""
firstName=""/>
</imdata>
This example logs out a user using the aaaLogout API method:
POST https://192.0.20.123/api/aaaLogout.json
<aaaUser name="admin" />
This example shows the response upon a successful logout:
<?xml version="1.0" encoding="UTF-8"?>

<imdata>
</imdata>

This example logs in a user by using a JSON data structure that contains the username and password:
{
"aaaUser":{
"attributes":{
"name":"georgewa",
"pwd":"paSSword1"
}
}
}
This example shows the response upon a successful login:
{
"imdata":[{
"aaaLogin":{
"attributes":{
"token":"token":
"GkZl5NLRZJl5+jqChouaZ9CYjgE58W/pMccR+LeXmdO0obG9NB
Iwo1VBo7+YC1oiJL9mS6I9qh62BkX+Xddhe0JYrTmSG4JcKZ4t3
bcP2Mxy3VBmgoJjwZ76ZOuf9V9AD6Xl83lyoR4bLBzqbSSU1R2N
IgUotCGWjZt5JX6CJF0=",
"refreshTimeoutSeconds":"300",
"lastName":"Washington",
"firstName":"George"
},
"children":[{
"aaaUserDomain":{
"attributes":{
"name":"all",
"rolesR":"0",
"rolesW":"2"
},
"children":[{
"aaaReadRoles":{
"attributes":{}
}
}, {
"aaaWriteRoles":{
"attributes":{},
"children":[{
"role":{
"attributes":{
"name":"admin"
}

23
}
}
]
}
}
]
}
}, {
"aaaUserDomain":{
"attributes":{
"name":"common",
"rolesR":"0",
"rolesW":"1"
},
"children":[{
"aaaReadRoles":{
"attributes":{}
}
}, {
"aaaWriteRoles":{
"attributes":{},
"children":[{
"role":{
"attributes":{
"name":"read-only"
}
}
}
]
}
}
]
}
}, {
"DnDomainMapEntry":{
"attributes":{
"dn":"uni/tn-common",
"readPrivileges":"0",
"writePrivileges":"3"
}
}
}
]
}
}
]
}
The response contains a session timeout period and a session token, along with domain and role information
about the user.
This example refreshes the session using the aaaRefresh API method:
GET https://192.0.20.123/api/aaaRefresh.json
This example shows the response upon a successful session refresh:
{
"imdata":[{
"aaaLogin":{
"attributes":{
"token":
"Zs8jf2rcseiiYydx9WbyRVOScWs6c0Orti7EBg1H02jt0JV9oe
icX1ULLquI+LCN/93cAf46AErXpT4kN0mrCQRcCMRAl6m0ObT/r
G4D9UTm6/NNnqzhntCWTKt9IovTFDpD8Ocx1oXn2jpmS6PYDBJt
Wp4rIAu11sdM8BA24g6=",
"refreshTimeoutSeconds":"0",
"lastName":"",
"firstName":""
}

24
Adding a Tenant
}
}
]
}
This example logs out a user using the aaaLogout API method:
POST https://192.0.20.123/api/aaaLogout.json
{
"aaaUser":{
"attributes":{
"name":"georgewa"
}
}
}
This example shows the response upon a successful logout:
{
"imdata":[]
}
Adding a Tenant
A tenant is a policy owner in the virtual fabric. A tenant can be either a private or a shared entity. For example,
you can create a securely partitioned private tenant or a tenant with contexts and bridge domains shared by
other tenants. A shared type of tenant is typically named common, default, or infra.
In the management information model, a tenant is represented by a managed object (MO) of class fv:Tenant.
According to the Cisco APIC Management Information Model Reference, an object of the fv:Tenant class is
a child of the policy resolution universe (uni) class and has a distinguished name (DN) format of uni/tn-[name].
The following examples show how to add a new tenant named ExampleCorp using XML and JSON.
Example: Using the XML API to Add a Tenant

To create a new tenant, you must specify the class and sufficient naming information, either in the message
body or in the URI.
To create a new tenant named ExampleCorp using the XML API, send this HTTP POST message:
<fvTenant name="ExampleCorp"/>
Alternatively, you can name the tenant in the URI, as in this example:
POST https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml
<fvTenant />
If a response is requested (by appending ?rsp-subtree=modified to the POST URI), a successful operation
returns the following response body:
<imdata>
<fvTenant
instanceId="0:0"

25
Example: Using the JSON API to Add a Tenant
childAction="deleteNonPresent"
dn="uni/tn-ExampleCorp"
lcOwn="local"
name="ExampleCorp"
replTs="never"
rn=""
status="created"
/>
</imdata>
To delete the tenant, send this HTTP DELETE message:
DELETE https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml
Alternatively, you can send an HTTP POST message with sufficient naming information and with
status="deleted" in the fv:Tenant attributes, as in this example:
<fvTenant name="ExampleCorp" status="deleted"/>
Example: Using the JSON API to Add a Tenant

To create a new tenant, you must specify the class and sufficient naming information, either in the message
body or in the URI.
To create a new tenant using the JSON API, send this HTTP POST message:
POST https://192.0.20.123/api/mo/uni.json
{
"fvTenant" : {
"attributes" : {
"name" : "ExampleCorp"
}
}
}
Alternatively, you can name the tenant in the URI, as in this example:
POST https://192.0.20.123/api/mo/uni/tn-ExampleCorp.json
{
"fvTenant" : {
"attributes" : {
}
}
}
{
"imdata" :
[{
"fvTenant" : {
"attributes" : {
"childAction" : "deleteNonPresent",
"dn" : "uni/tn-ExampleCorp",
"lcOwn" : "local",
"name" : "ExampleCorp",
"replTs" : "never",

26
Adding a User
"rn" : "",
}
}
}
]
}
To delete the tenant, send this HTTP DELETE message:
DELETE https://192.0.20.123/api/mo/uni/tn-ExampleCorp.json
Alternatively, you can send an HTTP POST message with sufficient naming information and with "status"
: "deleted" in the fv:Tenant attributes, as in this example:
POST https://192.0.20.123/api/mo/uni.json
{
"fvTenant" : {
"attributes" : {
"status" : "deleted"
}
}
}
Adding a User
An APIC user account contains, in addition to a name and password, information about the user's privilege
level (role) and the scope (domain) of the user's control in the fabric. A cloud administrator, for example,
might have global control, including the ability to create tenants and to assign additional administrators, while
a tenant administrator is typically restricted to the tenant's domain or network. When you configure a user
account, you can specify additional configuration items, such as a password expiration policy, or you can
omit those items to accept the default settings.
In the management information model, an APIC user is represented by a managed object (MO) of class
aaa:User. According to the Cisco APIC Management Information Model Reference, an object of the aaa:User
class has a distinguished name (DN) format of uni/userext/user-[name]. The direct properties (attributes)
of the aaa:User class do not include fields for the user domain or privilege level, but the reference for this
class indicates a child class (subtree) of aaa:UserDomain, which has a child class of aaa:UserRole. The API
command structure to add the new user can include the configuration of the user domain and privilege level
in these child classes in the following hierarchy:
• aaa:User—The user object can contain one or more user domain child objects.
◦aaa:UserDomain—The user domain object can contain one or more user role objects.
◦aaa:UserRole—The user role object specifies the privilege level of the user.
The following examples show how to add a new user to the user domain ExampleCorp with administrator
privileges using XML and JSON. An additional example shows how to use a cURL command to perform the
task from a command line.

27
Example: Using the XML API to Add a User
Example: Using the XML API to Add a User

To create a new object, you must specify the class and sufficient naming information, either in the URI or in
the message body. In this example, the URI contains the DN and the message body contains the object class.
To create and configure a new user using the XML API, send this HTTP POST message:
POST https://192.0.20.123/api/mo/uni/userext/user-georgewa.xml
<aaaUser
pwd="password1"
firstName="George"
lastName="Washington"
phone="4085551212"
email="georgewa@example.com" >
<aaaUserDomain name="ExampleCorp" >
<aaaUserRole name="admin" />
</aaaUserDomain>
</aaaUser>
Alternatively, you can POST to /api/mo.xml and provide the DN attribute dn="uni/userext/user-georgewa",
or you can POST to /api/mo/uni/userext.xml and provide the name attribute name="georgewa".
The children sections of this command structure configure the new user to be in the ExampleCorp user domain
with a role of admin in that user domain. When you create a new user, you can specify less information or
more information than is shown in this example. Additional attributes can be configured in subsequent
operations.
<imdata>
<aaaUser
instanceId="0:0"
accountStatus="active"
clearPwdHistory="no"
descr=""
dn="uni/userext/user-georgewa"
email="georgewa@example.com"
encPwd=""
expiration="never"
expires="no"
firstName="George"
intId="none"
lastName="Washington"
lcOwn="local"
name="georgewa"
phone="4085551212"
pwd="password1"
pwdLifeTime="no-password-expire"
pwdSet="no"
replTs="never"
rn=""
status="created" >
<aaaUserDomain
instanceId="0:0"
descr="" intId="none"
lcOwn="local"
name="common"
replTs="never"
rn="userdomain-common"
status="created" >
<aaaUserRole

28
Example: Using the JSON API to Add a User
instanceId="0:0"
descr=""
intId="none"
lcOwn="local"
name="read-only"
privType="readPriv"
replTs="never"
rn="role-read-only"
status="created" />
</aaaUserDomain>
<aaaUserDomain
instanceId="0:0"
descr=""
intId="none"
lcOwn="local"
name="ExampleCorp"
replTs="never"
rn="userdomain-ExampleCorp"
status="created" >
<aaaUserRole
instanceId="0:0"
descr=""
intId="none"
lcOwn="local"
name="admin"
privType="readPriv"
replTs="never"
rn="role-admin"
status="created" />
</aaaUserDomain>
</aaaUser>
</imdata>
This response indicates that the user has been created and added to two user domains. The user has admin
privileges in the ExampleCorp user domain, as requested. By default, the user also has read-only privileges
in the common user domain.
To delete the user, send this HTTP DELETE message:
DELETE https://192.0.20.123/api/mo/uni/userext/user-georgewa.xml
status="deleted" in the aaa:User attributes, as in this example:
POST https://192.0.20.123/api/mo.xml
<aaaUser dn="uni/userext/user-georgewa" status="deleted" />

To create and configure a new user using the JSON API, send this HTTP POST message:
POST https://192.0.20.123/api/mo/uni/userext/user-georgewa.json
{
"aaaUser" : {
"attributes" : {
"pwd" : "password1",

29
"firstName" : "George"
"phone" : "4085551212",
"email" : "georgewa@example.com"
},
"children" : [{
"aaaUserDomain" : {
"attributes" : {
"name" : "ExampleCorp"
},
"children" : [{
"aaaUserRole" : {
"attributes" : {
"name" : "admin"
}
}
}
]
}
}
]
}
}
Alternatively, you can POST to /api/mo.json and provide the DN attribute

"dn":"uni/userext/user-georgewa", or you can POST to /api/mo/uni/userext.json and provide the name
attribute "name":"georgewa".
The children sections of this command structure configure the new user to be in the ExampleCorp user domain
with a role of admin in that user domain. When you create a new user, you can specify less information or
more information than is shown in this example. Additional attributes can be configured in subsequent
operations.
{
"imdata" : [{
"aaaUser" : {
"attributes" : {
"accountStatus" : "active",
"clearPwdHistory" : "no",
"descr" : "",
"dn" : "uni/userext/user-georgewa",
"email" : "georgewa@example.com",
"encPwd" : "",
"expiration" : "never",
"expires" : "no",
"firstName" : "George",
"intId" : "none",
"lcOwn" : "local",
"name" : "georgewa",
"phone" : "5551212",
"pwd" : "password1",
"pwdLifeTime" : "no-password-expire",
"pwdSet" : "no",
"replTs" : "never",
"rn" : "",
},
"children" : [{
"aaaUserDomain" : {
"attributes" : {
"descr" : "",

30
"dn" : "",
"intId" : "none",
"lcOwn" : "local",
"name" : "common",
"replTs" : "never",
"rn" : "userdomain-common",
},
"children" : [{
"aaaUserRole" : {
"attributes" : {
"descr" : "",
"dn" : "",
"intId" : "none",
"lcOwn" : "local",
"name" : "read-only",
"privType" : "readPriv",
"replTs" : "never",
"rn" : "role-read-only",
}
}
}
]
}
}, {
"aaaUserDomain" : {
"attributes" : {
"descr" : "",
"dn" : "",
"intId" : "none",
"lcOwn" : "local",
"replTs" : "never",
"rn" : "userdomain-ExampleCorp",
},
"children" : [{
"aaaUserRole" : {
"attributes" : {
"descr" : "",
"dn" : "",
"intId" : "none",
"lcOwn" : "local",
"name" : "admin",
"privType" : "writePriv",
"replTs" : "never",
"rn" : "role-admin",
}
}
}
]
}
}
]
}
}
]
}
This response indicates that the user has been created and added to two user domains. The user has admin
privileges in the ExampleCorp user domain, as requested. By default, the user also has read-only privileges
in the common user domain.

31
Example: Using the JSON API to Add a User with cURL
To delete the user, send this HTTP DELETE message:
DELETE https://192.0.20.123/api/mo/uni/userext/user-georgewa.json
"status":"deleted" in the aaa:User attributes, as in this example:
POST https://192.0.20.123/api/mo.json
{
"aaaUser" : {
"attributes" : {
"dn" : "uni/userext/user-georgewa",
}
}
}
Example: Using the JSON API to Add a User with cURL

Create a local file that contains a JSON structure in the form shown in Example: Using the JSON API to Add
a User, on page 29. In this example, the filename is newuser.json, and the file is in a different directory.
On the cURL command line, you must specify the HTTP method (such as POST), the path and name of the
local file, and the URI of the API operation.
Using the curl command, send the JSON file in a POST message to the API as in this example:
curl -X POST --data "@../users/newuser.json"

https://192.0.20.123/api/mo/uni/userext/user-georgewa.json
Note Be sure to include the @ sign before the filename. The cURL tool is free and open software. You can find
detailed information about using cURL online.
returns the response body shown in Example: Using the JSON API to Add a User, on page 29.
To delete the user, edit the JSON file to contain a aaaUser attribute of "status":"deleted" and send the
command again.
Alternatively, you can send this HTTP DELETE message:
curl -X DELETE https://192.0.20.123/api/mo/uni/userext/user-georgewa.json

32
Deploying Endpoint Groups and Contracts for a Three-Tier Application
Deploying Endpoint Groups and Contracts for a Three-Tier

Application
A typical use case of the Cisco Application Centric Infrastructure (ACI) fabric is hosting a three-tier application
within a tenant network. You can configure endpoint groups and contracts for such an application using the
APIC REST API. In this example, the application is implemented using three servers—a web server, an
application server, and a database server, as shown in this figure:
The following are key components of the configuration:

• Endpoint groups (EPGs)—Each server represents an endpoint group, sourcing or consuming traffic from
other endpoint groups according to the contracts associated with each endpoint group.
• Contracts—Traffic to and from an endpoint is constrained by contracts, which apply filter sets for traffic
sourced from (provided by) the endpoint and traffic consumed by the endpoint.
• Filters—A filter specifies the data protocols to be allowed or denied by a contract that contains the filter.
The following network components are assumed to already exist:

• Bridge Domain (BD)—A Layer 2 network associated with the Layer 3 context.
• Context—A Layer 3 private network for communication between the servers.
• External port—A Layer 3 network port for external access to the application.
• Virtual Machine manager (VMM) and hypervisor components
• VLAN
Note For an expanded and comprehensive example of deploying a three-tier application, see the Cisco APIC
Getting Started Guide.

33
The configuration information is contained in a single XML structure that is sent to the distinguished name
(DN) of the tenant. In this example, the name of the tenant is ExampleCorp. To deploy the application using
the XML API, send this HTTP POST message:
POST https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml
Include this XML structure in the body of the POST message:
<fvTenant name="ExampleCorp">
<fvAp name="OnlineStore">
<fvAEPg name="web">
<fvRsBd tnFvBDName="bd1"/>
<fvRsCons tnVzBrCPName="rmi"/>
<fvRsProv tnVzBrCPName="web"/>
<fvRsDomAtt tDn="uni/vmmp-VMware/dom-datacenter"/>
</fvAEPg>
<fvAEPg name="db">
<fvRsProv tnVzBrCPName="sql"/>
</fvAEPg>
<fvAEPg name="app">
<fvRsProv tnVzBrCPName="rmi"/>
<fvRsCons tnVzBrCPName="sql"/>
</fvAEPg>
</fvAp>
<vzFilter name="http" >

<vzEntry dFromPort="80" name="DPort-80" prot="tcp" etherT="ip" />
</vzFilter>
<vzFilter name="rmi" >

</vzFilter>
<vzFilter name="sql">
</vzFilter>
<vzBrCP name="web">
<vzSubj name="web">
<vzRsSubjFiltAtt tnVzFilterName="http"/>
</vzSubj>
</vzBrCP>
<vzBrCP name="rmi">
<vzSubj name="rmi">
<vzRsSubjFiltAtt tnVzFilterName="rmi"/>
</vzSubj>
</vzBrCP>
<vzBrCP name="sql">
<vzSubj name="sql">
<vzRsSubjFiltAtt tnVzFilterName="sql"/>
</vzSubj>
</vzBrCP>
</fvTenant>
In the XML structure, the first line modifies, or creates if necessary, the tenant named ExampleCorp.
<fvTenant name="ExampleCorp">

34
This line creates an application network profile named OnlineStore:
<fvAp name="OnlineStore">
The elements within the application network profile create three endpoint groups, one for each of the three
servers. The following lines create an endpoint group named web and associate it with an existing bridge
domain named bd1. This endpoint group is a consumer, or destination, of the traffic allowed by the binary
contract named rmi and is a provider, or source, of the traffic allowed by the binary contract named web. The
endpoint group is associated with the VMM domain named datacenter.
<fvAEPg name="web">
<fvRsCons tnVzBrCPName="rmi"/>
<fvRsProv tnVzBrCPName="web"/>
</fvAEPg>
The remaining two endpoint groups, for the application server and the database server, are created in a similar
way.
The following lines define a traffic filter named http that specifies TCP traffic of types HTTP (port 80) and
HTTPS (port 443).
<vzFilter name="http">
<vzEntry dFromPort="80" name="DPort-80" prot="tcp" />
<vzEntry dFromPort="443" name="DPort-443" prot="tcp" />
</vzFilter>
The remaining two filters, for application data and database (sql) data, are created in a similar way.
The following lines create a binary contract named web that incorporates the filter named http:
<vzBrCP name="web">
<vzSubj name="web">
<vzRsSubjFiltAtt tnVzFilterName="http"/>
</vzSubj>
</vzBrCP>
The remaining two contracts, for rmi and sql data protocols, are created in a similar way.
The final line closes the structure:
</fvTenant>

35

36
CHAPTER 4
Using Tools for API Development and Testing
• Using the API Inspector, page 37

• Using the Managed Object Browser, page 39
• Testing the API, page 42
Using the API Inspector

Viewing an API Interchange in the GUI
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. .
Procedure
Step 1 Log in to the APIC GUI.

Step 2 In the upper right corner of the APIC window, click the "welcome, <name>" message to view the drop-down
list.
Step 3 In the drop-down list, choose the Show API Inspector.
The API Inspector opens in a new browser window.
Step 4 In the Filters toolbar of the API Inspector window, choose the types of API log messages to display.
The displayed messages are color-coded according to the selected message types. This table shows the available
message types:
Name Description
trace Displays trace messages.

37
Viewing an API Interchange in the GUI
Name Description
debug Displays debug messages. This type includes most API commands and responses.
info Displays informational messages.
warn Displays warning messages.
error Displays error messages.
fatal Displays fatal messages.
all Checking this checkbox causes all other checkboxes to become checked. Unchecking any
other checkbox causes this checkbox to be unchecked.
Step 5 In the Search toolbar, you can search the displayed messages for an exact string or by a regular expression.
This table shows the search controls:
Name Description
Search In this text box, enter a string for a direct search or enter a regular expression for a regex
search. As you type, the first matched field in the log list is highlighted.
Reset Click this button to clear the contents of the Search text box.
Regex Check this checkbox to use the contents of the Search text box as a regular expression for
a search.
Match case Check this checkbox to make the search case sensitive.
Disable Check this checkbox to disable the search and clear the highlighting of search matches in
the log list.
Next Click this button to cause the log list to scroll to the next matched entry. This button
appears only when a search is active.
Previous Click this button to cause the log list to scroll to the previous matched entry. This button
appears only when a search is active.
Filter Check this checkbox to hide nonmatched lines. This checkbox appears only when a search
is active.
Highlight all Check this checkbox to highlight all matched fields. This checkbox appears only when a
search is active.
Step 6 In the Options toolbar, you can arrange the displayed messages.
This table shows the available options:
Name Description
Log Check this checkbox to enable logging.
Wrap Check this checkbox to enable wrapping of lines to avoid horizontal scrolling of the log
list

38
Using the Managed Object Browser
Name Description
Newest at the Check this checkbox to display log entries in reverse chronological order.
top
Scroll to latest Check this checkbox to scroll immediately to the latest log entry.
Clear Click this button to clear the log list.
Close Click this button to close the API Inspector.
Example
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":[]}
Using the Managed Object Browser

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.
Accessing Visore
Procedure
Step 1 Open a supported browser and enter the URL of the APIC followed by /visore.html.
Example:
https://192.0.20.123/visore.html
Step 2 When prompted, log in using the same credentials you would use to log in to the APIC CLI or GUI user
interfaces.

39
Visore Browser Page
You can use a read-only account.
Visore Browser Page

Filter Area
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:
• == (equal to)
• != (not equal to)
• < (less than)
• > (greater than)
• ≤ (less than or equal to)
• ≥ (greater than or equal to)
• between
• wildcard
• anybit
• allbits
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.
Display XML of Last Query Link

The Display XML of last query link displays the full APIC REST API translation of the most recent query
run in Visore.

40
Running a Query in Visore
Results Area
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.
Running a Query in Visore

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

41
Testing the API
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

Testing the API Using Browser Add-Ons
Using a Browser
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:
• For Firefox/Mozilla—Poster, RESTClient
• For Chrome—Advanced REST client, Postman
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.
Testing the API with cURL

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

42
Testing the API with Python
Note When testing with cURL, you must log in to the API, store the authentication token, and include the token
in subsequent API operations.
Related Topics
Example: Using the JSON API to Add a User with cURL, on page 32

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)
# 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.

43

44
APPENDIX A
Uploading a Device Package File Using the API
• Uploading a Device Package File Using the API, page 45

To install a layer 4 through layer 7 (L4-L7) service device, you must upload a device package file to APIC.
The API command for this operation uses a special form of URI:
{http| https}://host[ :port ]/ppi/node/mo/.{json| xml}
The URI path contains 'ppi' (package programming interface) instead of 'api', and the command is sent as a
POST operation with the device package file as the body of the message. The device package file is a zip file.
This example shows an API operation that uploads a device package file:
POST https://192.0.20.123/ppi/node/mo/.json
For more information about installing L4-L7 service device packages, see Cisco APIC Layer 4 to Layer 7
Services Deployment Guide .

45

46
APPENDIX B
Additional Examples
• Information About the API Examples, page 47

• Example: Using the JSON API to Get Top Level System Elements, page 47
• Example: Using the JSON API to Get Information About a Node, page 48
• Example: Using the JSON API to Get Running Firmware, page 49
• Example: Using the JSON API to Add a Leaf Port Selector Profile, page 50
Information About the API Examples

In the examples, the JSON and XML structures have been expanded with line feeds, spaces, and indentations
for readability.
Example: Using the JSON API to Get Top Level System Elements
This example shows how to query the APIC to determine what system devices are present.
General information about the system elements (APICs, spines, and leafs) is contained in an object of class
top:System.
This example shows the API query message:
GET http://192.0.20.123/api/class/topSystem.json
A successful operation returns a response body similar to this example:
{
"imdata" :
[{
"topSystem" : {
"attributes" : {
"address" : "10.0.0.32",
"childAction" : "",
"currentTime" : "2013-06-14T04:13:05.584",
"currentTimeZone" : "",

47
Additional Examples
Example: Using the JSON API to Get Information About a Node
"dn" : "topology/pod-1/node-17/sys",
"fabricId" : "0",
"id" : "17",
"inbMgmtAddr" : "0.0.0.0",
"lcOwn" : "local",
"mode" : "unspecified",
"name" : "leaf0",
"nodeId" : "0",
"oobMgmtAddr" : "0.0.0.0",
"podId" : "1",
"replTs" : "never",
"role" : "leaf",
"serial" : "FOX-270308",
"status" : "",
"systemUpTime" : "00:00:02:03"
}
}
}, {
"topSystem" : {
"attributes" : {
"address" : "10.0.0.1",
"childAction" : "",
"currentTime" : "2013-06-14T04:13:29.301",
"currentTimeZone" : "PDT",
"dn" : "topology/pod-1/node-1/sys",
"fabricId" : "0",
"id" : "1",
"inbMgmtAddr" : "0.0.0.0",
"lcOwn" : "local",
"mode" : "unspecified",
"name" : "apic0",
"nodeId" : "0",
"oobMgmtAddr" : "0.0.0.0",
"podId" : "0",
"replTs" : "never",
"role" : "apic",
"serial" : "",
"status" : "",
"systemUpTime" : "00:00:02:26"
}
}
}
]
}
This response indicates that the system consists of one APIC (node-1) and one leaf (node-17).
Example: Using the JSON API to Get Information About a Node

This example shows how to query the APIC to access a node in the system.
To direct an API operation to a specific node device in the fabric, the resource path consists of
/mo/topology/pod-number/node-number/sys/ followed by the node component. For example, this URI
accesses board sensor 3 in chassis slot B of node 1:
GET http://192.0.20.123/api/mo/topology/pod-1/node-1/sys/ch/bslot/board/sensor-3.json
{
"imdata" :
[{
"eqptSensor" : {
"attributes" : {

48
Additional Examples
Example: Using the JSON API to Get Running Firmware
"childAction" : "",
"dn" : "topology/pod-1/node-1/sys/ch/bslot/board/sensor-3",
"id" : "3",
"majorThresh" : "0",
"mfgTm" : "not-applicable",
"minorThresh" : "0",
"model" : "",
"monPolDn" : "",
"rev" : "0",
"ser" : "",
"status" : "",
"type" : "dimm",
"vendor" : "Cisco Systems, Inc."
}
}
}
]
}
Example: Using the JSON API to Get Running Firmware

This example shows how to query the APIC to determine which firmware images are running.
The detailed information on running firmware is contained in an object of class firmware:IfcRunning, which
is a child class (subtree) of the APIC firmware status container class firmware:IfcFwStatusCont. Because
there can be multiple running firmware instances (one per APIC instance), you can query the container class
and filter the response for the subtree of running firmware objects.
This example shows the API query message:
GET http://192.0.20.123/api/class/firmwareIfcFwStatusCont.json?
query-target=subtree
&
target-subtree-class=firmwareIfcRunning
{
"imdata" : [{
"firmwareIfcRunning" : {
"attributes" : {
"applId" : "3",
"childAction" : "",
"dn" : "ifcfwstatuscont/ifcrunning-3",
"lcOwn" : "local",
"replTs" : "never",
"rn" : "",
"status" : "",
"ts" : "2012-12-31T16:00:00.000",
"type" : "ifc",
"version" : "1.1"
}
}
}, {
"attributes" : {
"applId" : "1",
"childAction" : "",
"lcOwn" : "local",
"replTs" : "never",
"rn" : "",
"status" : "",

49
Additional Examples
Example: Using the JSON API to Add a Leaf Port Selector Profile
"ts" : "2012-12-31T16:00:00.000",
"type" : "ifc",
"version" : "1.1"
}
}
}, {
"attributes" : {
"applId" : "2",
"childAction" : "",
"lcOwn" : "local",
"replTs" : "never",
"rn" : "",
"status" : "",
"ts" : "2012-12-31T16:00:00.000",
"type" : "ifc",
"version" : "1.1"
}
}
}
]
}
This response describes three running instances of APIC firmware version 1.1.
This example shows how to add a leaf port selector profile.
As shown in the Cisco APIC Management Information Model Reference, this hierarchy of classes forms a
leaf port selector profile:
• fabric:LePortP — A leaf port profile is represented by a managed object (MO) of this class, which has
a distinguished name (DN) format of uni/fabric/leportp-[name], in which leportp-[name] is the
relative name (RN). The leaf port profile object is a template that can contain a leaf port selector as a
child object.
◦fabric:LFPortS — A leaf port selector is represented by an MO of this class, which has a RN format
of lefabports-[name]-typ-[type]. The leaf port selector object can contain one or more ports
or ranges of ports as child objects.
◦fabric:PortBlk — A leaf port or a range of leaf ports is represented by an MO of this class,
which has a RN format of portblk-[name].
The API command that creates the new leaf port selector profile MO can also create and configure the child
MOs.
This example creates a leaf port selector profile with the name "MyLPSelectorProf." The example profile
contains a selector named "MySelectorName" that selects leaf port 1 on leaf switch 1 and leaf ports 3 through
5 on leaf switch 1. To create and configure the new profile, send this HTTP POST message:
POST http://192.0.20.123/api/mo/uni/fabric/leportp-MyLPSelectorProf.json
{
"fabricLePortP" : {
"attributes" : {
"descr" : "Selects leaf ports 1/1 and 1/3-5"
},
"children" : [{

50
Additional Examples
"fabricLFPortS" : {
"attributes" : {
"name" : "MySelectorName",
"type" : "range"
},
"children" : [{
"fabricPortBlk" : {
"attributes" : {
"fromCard" : "1",
"toCard" : "1",
"fromPort" : "1",
"toPort" : "1",
"name" : "block2"
}
}
}, {
"fabricPortBlk" : {
"attributes" : {
"fromCard" : "1",
"toCard" : "1",
"fromPort" : "3",
"toPort" : "5",
"name" : "block3"
}
}
}
]
}
}
]
}
}
A successful operation returns this response body:
{
"imdata" : [{
"fabricLePortP" : {
"attributes" : {
"descr" : "Select leaf ports 1/1 and 1/3-5",
"dn" : "uni/fabric/leportp-MyLPSelectorProf",
"lcOwn" : "local",
"name" : "MyLPSelectorProf",
"replTs" : "never",
"rn" : "",
},
"children" : [{
"fabricLFPortS" : {
"attributes" : {
"dn" : "",
"lcOwn" : "local",
"name" : "MySelectorName",
"replTs" : "never",
"rn" : "lefabports-MySelectorName-typ-range",
"status" : "created",
"type" : "range"
},
"children" : [{
"fabricPortBlk" : {
"attributes" : {
"dn" : "",
"fromCard" : "1",
"fromPort" : "3",
"lcOwn" : "local",
"name" : "block3",

51
Additional Examples
"replTs" : "never",
"rn" : "portblk-block3",
"toCard" : "1",
"toPort" : "5"
}
}
}, {
"fabricPortBlk" : {
"attributes" : {
"dn" : "",
"fromCard" : "1",
"fromPort" : "1",
"lcOwn" : "local",
"name" : "block2",
"replTs" : "never",
"rn" : "portblk-block2",
"toCard" : "1",
"toPort" : "1"
}
}
}
]
}
}
]
}
}
]
}
To delete the new profile, send an HTTP POST message with a fabricLePortP attribute of "status":"deleted",
as in this example:
POST http://192.0.20.123/api/mo/uni/fabric/leportp-MyLPSelectorProf.json
{
"fabricLePortP" : {
"attributes" : {
}
}
}
Alternatively, you can send this HTTP DELETE message:
DELETE http://192.0.20.123/api/mo/uni/fabric/leportp-MyLPSelectorProf.json

52
APPENDIX C
Configuring the Communication Policy
• Configuring HTTP and HTTPS Using the GUI, page 53
Configuring HTTP and HTTPS Using the GUI

This procedure configures the supported communication protocol for access to the GUI and the REST API.
By default, only HTTPS is enabled. HTTP or HTTP-to-HTTPS redirection, if desired, must be explicitly
enabled and configured. HTTP and HTTPS can coexist.
Procedure
Step 1 On the menu bar, click FABRIC > Fabric Policies.

Step 2 In the Navigation pane, expand Pod Policies > Policies > Communication.
Step 3 Under Communication, click the default policy.
Step 4 In the Work pane, in the HTTP or HTTPS areas, enable or disable the protocol by selecting the desired state
from the Admin State drop-down list.
Step 5 In the HTTP area, enable or disable HTTP-to-HTTPS redirection by selecting the desired state from the
Redirect drop-down list.
Step 6 Click Submit.

53
Configuring the Communication Policy
Configuring HTTP and HTTPS Using the GUI

54
INDEX
A example (continued)
get top level system elements 47
about the API 3
API 3
information about 3
API Inspector 37 F
authentication 9, 11 filtering query results 12
firmware 49
example of query 49
C
challenge token 11
concrete object 1 G
Content-Type 6 GET 6
specifying 6
cURL 32, 42
example 32
using 42 J
JSON 3
D
deploying a three-tier application (XML) 33 L
distinguished name 2
description 2 logical object 1
DME 3 login 9, 22, 23
logout 9, 22, 23
logs 37
E
example 22, 23, 25, 26, 28, 29, 32, 47, 48, 49, 50 M
adding a profile 50
adding a tenant (JSON) 26 managed object, See MO
adding a tenant (XML) 25 managed object browser 39
adding a user (JSON) 29 management information model, See MIM
adding a user (XML) 28 management information tree 3
adding a user with cURL 32 See also MIM
authenticating a user (JSON) 23 MIM 1
authenticating a user (XML) 22 MO 1
get node information 48 concrete 1
get running firmware 49 logical 1

IN-1
Index
N tenant 25, 26
example of adding (JSON) 26
node 48 example of adding (XML) 25
example of accessing 48 testing 42, 43
using browser add-on 42
using cURL 42
P using Python 43
three-tier application 33
POST 6 deploying (XML) 33
profile 50 timeout 9, 22, 23
example of adding 50
Python 43
using 43
U
URI 6
Q structure 6
user 22, 23, 28, 29, 32
query 12, 14, 16 example of adding (JSON) 29
filter expressions 14 example of adding (XML) 28
filtering 12 example of adding with cURL 32
scoping 12 example of authenticating (JSON) 23
subscribing 16 example of authenticating (XML) 22
R V
refresh 9, 22, 23 Visore utility 39, 41
relative name 2 accessing 39
example 2 description 39
REST architecture 3 running a query 41
S W
scoping query results 12 WebSocket 16
subscription 16
X
T
XML 3
tags 19

IN-2

Cisco APIC REST API User Guide

Uploaded by

Copyright:

Available Formats

Cisco APIC REST API User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cisco APIC REST API User Guide

Uploaded by

Copyright:

Available Formats

Cisco APIC REST API User Guide

First Published: October 31, 2013

© 2013-2014 Cisco Systems, Inc. All rights reserved.

Preface Preface vii

CHAPTER 1 Overview of the APIC REST API 1

CHAPTER 2 Using the APIC REST API 5