The Application Policy Infrastructure
Controller (APIC) REST API is a programmatic interface that uses REST architecture. The API accepts and returns HTTP (not enabled by default)
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 REST API is the interface into the management information tree (MIT) and allows manipulation of the object model state.
The same REST interface is used by the APIC CLI, GUI, and SDK, so that whenever information is displayed, it is read through the REST API, and when configuration changes
are made, they are written through the REST API. The REST API also provides an interface through which other information can
be retrieved, including statistics, faults, and audit events. It even provides a means of subscribing to push-based event
notification, so that when a change occurs in the MIT, an event can be sent through a web socket.
Standard REST methods are supported on the API, which includes POST, GET, and DELETE operations through HTTP. The POST and
DELETE methods are idempotent, meaning that there is no additional effect if they are called more than once with the same
input parameters. The GET method is nullipotent, meaning that it can be called zero or more times without making any changes
(or that it is a read-only operation).
Payloads to and from the REST interface can be encapsulated through either XML or JSON encoding. In the case of XML, the encoding
operation is simple: the element tag is the name of the package and class, and any properties of that object are specified
as attributes of that element. Containment is defined by creating child elements.
For JSON, encoding requires definition of certain entities to reflect the tree-based hierarchy; however, the definition is
repeated at all levels of the tree, so it is fairly simple to implement after it is initially understood.
-
All objects are described as JSON dictionaries, in which the key is the name of the package and class. The value is another
nested dictionary with two keys: attribute and children.
-
The attribute key contains a further nested dictionary describing key-value pairs that define attributes on the object.
-
The children key contains a list that defines all the child objects. The children in this list are dictionaries containing
any nested objects, which are defined as described here.
Authentication
REST API username- and password-based authentication uses a special subset of request Universal Resource Identifiers (URIs),
including aaaLogin, aaaLogout, and aaaRefresh as the DN targets of a POST operation. Their payloads contain a simple XML or JSON payload containing the MO representation
of an aaaUser object with the attribute name and pwd defining the username and password: for example, <aaaUser name='admin' pwd='password'/>. The response to the POST operation will contain an authentication token as both a Set-Cookie header and an attribute to
the aaaLogin object in the response named token, for which the XPath is /imdata/aaaLogin/@token if the encoding is XML. Subsequent operations on the REST API can use this token value as a cookie named APIC-cookie to authenticate future requests.
Subscription
The REST API supports the subscription to one or more MOs 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 the event changes the data on any of the
active subscribed queries, the APIC will send out a notification to the API client that created the subscription.
Feedback