Manage Cisco ACI with REST API [Explained]

I- ACI Policy Model Objects:

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.

Objects within APIC are structured in tree-based hierarchy:

• Objects referred to as “managed objects” (MO)

• Packages identify the functional area

– e.g., fv = fabric virtualization, vz = virtual zones,

– fabric = physical fabric, etc

• Every object has a parent, with exception of top:Root (top of tree)

• Relationships exist between objects
  
  

• Class identifies object type:
  Card, Port, Path, EPG…
• Class Inheritance:
  Access port is a subclass of port.
  A leaf node is a subclass of fabric node.

Management Information Tree Example:

Distinguished Name:

• DN is used as a globally unique identifier for an object in the MIT.
• Formed by getting relative name (RN) and appending it to parent RN until reaching topRoot
• RN naming rule depends on the object (Can be found in APIC model documentation)

• Example-1:
  EPG in a tenant named “tenant” under
  application “app1”
  uni/tn-tenant/ap-app1/epg-epg1

• Example-2:
  Interface Eth1/3 on leaf 102 in pod 1
  topology/pod-1/paths-102/pathep-[eth1/3]

II- REST API in ACI APIC

* Supported REST API Methods in ACI:

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

* APIC REST API Read Operations:

Example:

• Read properties for an EPG by Distinguished Name:

<strong>http://apic/api/mo/uni/tn-Cisco/ap-Software/epg-Download.xml</strong>Code language: HTML, XML (xml)

Query Filters:

• Usually more efficient as less number of MOs need to be serialized and returned
  • Filter the response returned using the supplied condition(s):
  – Syntax: http://URI?condition[&condition[&…]]
  • Returns only the MOs that satisfies the condition(s)

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

Note	A scoping filter can contain a maximum of 20 ‘(attribute,value)‘ filter expressions. If the limit is exceeded, the API returns an error.

Example of Query Filters:

• Find all 10G ports on Fabric:

<strong>http://apic/api/class/l1PhysIf.xml?query-target-filter=eq(l1PhysIf.speed,"10G</strong>")Code language: HTML, XML (xml)

• This example returns all managed objects of class aaaUser whose last name is equal to “Washington”:

GET https://<var>apic-ip-address</var>/api/class/aaaUser.json?
      query-target-filter=eq(aaaUser.lastName,"Washington")Code language: HTML, XML (xml)

• This example returns endpoint groups whose fabEncap property is “vxlan-12780288”:

GET https://<var>apic-ip-address</var>/api/class/fvAEPg.xml?
    query-target-filter=eq(fvAEPg.fabEncap,"vxlan-12780288")Code language: HTML, XML (xml)

• This example shows all tenant objects with a current health score of less than 50:

GET https://<var>apic-ip-address</var>/api/class/fvTenant.json?
    rsp-subtree-include=health,required
        &
        rsp-subtree-filter=lt(healthInst.cur,"50")Code language: PHP (php)

• This example returns all endpoint groups and their faults under the tenant ExampleCorp:

GET https://<var>apic-ip-address</var>/api/mo/uni/tn-ExampleCorp.xml?
    query-target=subtree
        &
        target-subtree-class=fvAEPg
            &
            rsp-subtree-include=faultsCode language: JavaScript (javascript)

• This example returns aaa:Domain objects whose names are not “infra” or “common”:

GET https://<var>apic-ip-address</var>/api/class/aaaDomain.json?
    query-target-filter=
        and(ne(aaaDomain.name,"infra"),
            ne(aaaDomain.name,"common"))Code language: JavaScript (javascript)

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=<var>className</var>Code language: JavaScript (javascript)

This example requests information about the running firmware. The information is contained in the firmware:CtrlrRunning subtree (child) object of the APIC firmware status container firmware:CtrlrFwStatusCont:

GET https://<var>apic-ip-address</var>/api/class/firmwareCtrlrFwStatusCont.json?
    query-target=subtree&target-subtree-class=firmwareCtrlrRunningCode language: JavaScript (javascript)

* APIC REST API Create/Update Operations:

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.

Example: Using the JSON API to Add a Leaf Port Selector Profile:

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:

<strong>POST http://<var>apic-ip-address</var>/api/mo/uni/fabric/leportp-MyLPSelectorProf.json</strong>Code language: HTML, XML (xml)

JSON request Payload:

{
  "fabricLePortP" : {
    "attributes" : {
      "descr" : "Selects leaf ports 1/1 and 1/3-5"
    },
    "children" : [{
        "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"
                }
              }
            }
          ]
        }
      }
    ]
  }
}Code language: JSON / JSON with Comments (json)

Reference:

cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/rest_cfg/2_1_x/b_Cisco_APIC_REST_API_Configuration_Guide/b_Cisco_APIC_REST_API_Configuration_Guide_chapter_01.html

slideshare.net/CiscoDevNet/apic-dc-api-deep-dive