Server Infrastructure Required

This lab can be completed if you have access to the server infrastructure in a private lab or if you are at an event such as Cisco Live!

ACI 102: API Overview

Learning Objectives

After completing this module you will be able to:

  • Make API calls with JSON or XML payload
  • Understand the API Object Model and its tree structure
  • Differentiate ACI Objects by Name and by Class

API Review from ACI 101

In the first Module, we issued three main API calls:

  • POST: Create Tenant & Private-Network
  • GET: All Tenants
  • GET: All Private-Networks for a specific Tenant

No two RESTful APIs are identical and so whether you're a novice scripter or an experienced programmer, it will be helpful to delve into the specifics of the APIC API to get a better understanding of how to structure your calls. First we'll cover some background information on the APIC and its API and then run through some concrete examples.

Payload Format

As was discussed in the last module, ACI supports two formats in the Body of its REST calls:

  • JSON
  • XML

For the purposes of creating a script or a simple program you should consider these options as having equal merit but a significantly different approach for representing the data we are reading and writing to the APIC controller.
To compare these options recall the JSON payload we used to create a new tenant and private network:

{
    "polUni": {
        "attributes" : {}
          "children":[{
              "fvTenant" : {
                  "attributes" : {
                      "name" : "ExampleApiTenant"
                  }
                  "children": [{
                      "fvCtx": {
                        "attributes": {
                            "name": "myVRF"
                        }
                    }
                  }]
              }
          }]
    }
}

The XML payload for this same REST call would be:

<polUni>
    <fvTenant name="ExampleApiTenant">
        <fvCtx name="myVRF"/>
    </fvTenant>
</polUni>

In order to execute the REST call with this XML payload, we would also need to change the URL to end with .xml rather than .json.

https://<IP-of-APIC>/api/node/mo.xml

As you can see, using XML yields a similar hierarchy with the private network being contained within the tenant and so on. However, in this case the XML format is MUCH easier to write and to understand. There may be API calls in which the opposite is true – reading and writing in JSON may be preferable. You should feel free to use the option that works best for you. (Please note that many ACI programming examples on the web use XML. In an effort to provide more JSON examples, we'll use JSON for the remainder of this module.)

The ACI Management Information Tree (MIT)

So far we have seen a few examples of the hierarchal nature of components within ACI. In order to understand how to build the proper API calls, we'll spend a bit of time learning about this structure. All the physical and logical components that comprise the ACI fabric are represented in a hierarchical management information model (MIM), also known as a 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 with the Policy Universe at the top (Root) and each node contains parent and child nodes. Each node in the tree is an MO which represents a physical object, such as a switch or adapter, or a logical object, such as a policy or fault. Below is the upper-most view of the tree with the Policy Universe and the various types of MOs directly connected to it. Each MO below the Policy Universe also has many child MOs of its own, further extending the tree.

Figure

The entire MIT is quite extensive. Fortunately we can begin making useful scripts with only rudimentary understanding of the tree. For example, below is an overview of the Tenant portion of the MIT.

Figure

When we use the API, we take this MIT structure into account. We already examined the payload for our API call to create a new tenant and private network. In that JSON format, see the tree – the VRF is a child of the tenant which is a child of the policy universe (polUni).

Carriculum for These Learning Labs

The full feature set of ACI is exposed in the API, which allows us to interact with the fabric for a variety of use cases - scripting, automation, orchestration, troubleshooting and many more. Throughout these foundational learning modules on ACI, we'll focus on using the API to build automation scripts for Managed Objects in the Tenant subtree portion of the Model. As such, most of our API calls will be POSTing configurations to the APIC. In the intermediate/ACI 200 labs we'll begin to explore other use cases which involve querying the APIC to retrieve and format information using GET calls.

Assignment: Create a Bridge Domain

A Bridge Domain (BD) is a layer 2 space within ACI, similar to a broadcast domain but with several advantages. Unlike traditional broadcast domains which typically represent a single VLAN or Subnet, a BD may contain many subnets. Recall in the Tenant MIM diagram we saw earlier in this module, that a BD is also an MO, just like a Tenant or CTX, and the Subnet(s) for a BD are child MO's of the BD itself. In a traditional network, a layer 2 broadcast domain must be associated with a VRF. Similarly, in the MIM diagram, we see that the BD MO has a child relationship with a Context (or private network) MO. Now let's take the information we've learned in this Module and add a BD and subnet to our ACI tenant and private network. To add a BD, here are some important details we'll need to consider:

  • The MO name for a Bridge Domain is fvBD. Like the private network, the Bridge Domain is part of the virtual fabric, hense the fv prefix.
  • We will need to create a child object to contain the Subnet for this BD. The name of this MO is fvSubnet.
  • In the Subnet MO we'll need to specify the Subnet and the Subnet's Anycaste gateway provided by the ACI fabric. We can do this by assigning a value to the 'ip' attribute in the fvSubnet MO. The value should have the following format: {default-gateway-address}/{Subnet-size}. For example: 192.168.1.1/24.
  • The BD also requires another child MO which is used to relate itself to the private network we already created. This name for this MO is fvRsCtx and it will have an attribute called 'tnFvCtxName' which must match the name of the private network. In this case it must be 'myVRF'.

Now try to create an API POST to the APIC to add this bridge domain. You can use XML or JSON; both solutions are posted next.

Solution

Below is the APIC REST call to create a new BD, called 'myBD', with a single subnet '192.168.1.1/24' and relate it to the private network, 'myVRF'. First, here is the call in JSON:

POST: https://{IP-of-APIC}/api/node/mo/uni.json 
 {
    "polUni": {
        "attributes" : {}
        "children":[{
            "fvTenant" : {
                "attributes" : {
                    "name" : "ExampleApiTenant"
                }
                "children": [{
                    "fvBD": {
                        "attributes": {
                            "name": "myBD"
                        }

                       "children" : [{
                            "fvSubnet" : {
                                "attributes" : {
                                    "ip" : "192.168.1.1/24"
                                 }
                             }
                       },
                       {
                             "fvRsCtx" : {
                                 "attributes" : {
                                    "tnFvCtxName" : "myVRF"
                                 }
                             }                           
                        }]         
                    }
                }]
            }
        }]
    }
}

Second, here is the same solution with XML:

POST: https://{IP-of-APIC}/api/node/mo/uni.xml
<polUni>

    <fvTenant name="ExampleApiTenant" >

        <fvBD name="myBD">

            <fvRsCtx tnFvCtxName="myVRF" />

            <fvSubnet ip="192.168.1.1/24" />

        </fvBD>

    </fvTenant>

</polUni>