Cisco ACI API Basics: Login, Class Query, Managed Objects

Mental model

Cisco objective 3.9.a also includes ACI. ACI is Cisco’s data-center fabric; it is controlled by a cluster of APICs (Application Policy Infrastructure Controllers). The REST API is on each APIC, usually https://apic1.example.com/api/.

ACI’s model is different from most Cisco APIs:

• Everything is a Managed Object (MO). Switches, interfaces, tenants, bridge domains, EPGs, contracts.
• MOs form a tree under a root called polUni (policy universe).
• Each MO has a Distinguished Name (DN) that spells its path through the tree, e.g. uni/tn-Acme/BD-Web.
• The API lets you GET the MOs by class (every tenant: fvTenant) or by DN (one specific MO).

Login (cookie auth)

curl -k -c cookie.jar -X POST \
     -H "Content-Type: application/json" \
     -d '{"aaaUser":{"attributes":{"name":"admin","pwd":"password"}}}' \
     https://apic1.example.com/api/aaaLogin.json

• -c cookie.jar tells curl to save response cookies to a file.
• APIC responds with a JSON body AND a Set-Cookie: APIC-cookie=... header.
• From now on, pass -b cookie.jar on every call to send the cookie back.

Response (abbreviated):

{
  "imdata": [{"aaaLogin": {"attributes": {
    "token": "GgAAAAAAAAAAAAAAAAAAAA==", "refreshTimeoutSeconds": "600"
  }}}]
}

Cookie-based session; expires after refreshTimeoutSeconds seconds (default ~600). Call POST /api/aaaRefresh.json to extend.

3.9.a — List tenants (class query)

curl -k -b cookie.jar https://apic1.example.com/api/node/class/fvTenant.json

Response:

{
  "totalCount": "3",
  "imdata": [
    {"fvTenant": {"attributes": {"name": "common", "dn": "uni/tn-common"}}},
    {"fvTenant": {"attributes": {"name": "Acme", "dn": "uni/tn-Acme"}}},
    {"fvTenant": {"attributes": {"name": "mgmt", "dn": "uni/tn-mgmt"}}}
  ]
}

Every response wraps results in imdata (an array of per-MO objects). Each MO entry has an attributes dict and sometimes children.

List fabric devices

curl -k -b cookie.jar https://apic1.example.com/api/node/class/fabricNode.json

Returns every spine + leaf + APIC in the fabric. Attributes include id, name, role (spine / leaf / controller), model, serial, fabricSt (active / inactive).

Query by DN

curl -k -b cookie.jar https://apic1.example.com/api/node/mo/uni/tn-Acme.json

Pulls one specific MO (and optionally its children with ?query-target=children).

Python with requests

import requests
requests.packages.urllib3.disable_warnings()

BASE = "https://apic1.example.com"
session = requests.Session()

# login
session.post(f"{BASE}/api/aaaLogin.json",
             json={"aaaUser": {"attributes": {"name": "admin", "pwd": "password"}}},
             verify=False)

# list tenants
r = session.get(f"{BASE}/api/node/class/fvTenant.json", verify=False)
for entry in r.json()["imdata"]:
    tn = entry["fvTenant"]["attributes"]
    print(tn["name"], tn["dn"])

A Session() object persists the cookie across calls automatically.

Common ACI MO classes worth knowing

Common gotchas

• Cookie expires in minutes. Catch 403 and re-login, or call aaaRefresh.json on a timer.
• XML or JSON. APIC accepts both; use .json extension on URL for JSON.
• Case-sensitive class names. fvTenant works; fvtenant returns empty.
• Trailing-slash sensitivity. APIC is strict about URL shape.
• Child vs self query. ?query-target=children returns children, not the parent. ?query-target=subtree returns the whole sub-tree below.

FAQ

Is the ACI API REST? Yes, HTTP + JSON (or XML). It is RESTful but with its own model (MOs, DNs) rather than resource-per-URL.

What is the cobra Python SDK? acicobra is Cisco’s Python SDK for ACI. Models every MO as a Python class. For 200-901, requests + Session is enough.

Can I use NETCONF/RESTCONF against ACI? No, APIC uses its own management plane. The per-leaf Nexus 9000s do speak NX-API / RESTCONF but managed-by-APIC fabrics expect you to drive via the APIC.

Where do I practice without a real fabric? DevNet Sandbox has an always-on ACI simulator. Credentials on its sandbox page.