If you have upgraded your ACI to verison 5.1 or the recently released 5.2, you’ll notice a big change if you should ever venture to that rather obscure menu item Settings > Documentation > API Documentation

What’s the difference?

What you used to get was a basic but wholesome view of the Cisco APIC Management Information Reference Model, with a list of all the Classes, Types, Events, Faults etc listed on the left side, with clickable links associated with each Class etc.

Clicking on one of the links opened a Pandora’s Box of information in the viewing pane. One of my favourites is fv:Tenant

I’ve taken a bit of an extreme here – fv:Tenant is probably the largest class by far of the whole ACI Object model. For fun, I copied the information (text only) of the information pane above and pasted it in MS Word. I now have a 4140 page (556818 words) document that I can browse!

But if you knew how to navigate the page (there are a few handy shortcuts at the top) and use your browser’s find function, you could generally find what you wanted. Although, I must admit, the shortcuts at the top of the page may not work until the thousands of lines of content have loaded – which may be many seconds.

The new opening screen now presents a very fine search function – I has only to type the letters fvte before the search had located the fvTenant object. Happy to see the search is NOT case sensitive.

But there are a couple of other subtle improvements too. There is a toggle on the right-hand side that (by default) restricts your search to configurable objects. And you can only search all Objects or Faults via tabs at the top left-hand side. I think everyone always used the All group in the old system, so I’m happy with this improvement.

Having found my object, clicking on it opens a sub-window on the right-hand side, which has a second link that I must click to actually see the information I need.

At first, I was annoyed at having to click twice, [edit:2021.06.19 Turns out you can just double-click the name] but in other contexts where you have a list of objects, you’ll find the information window stays open as you click on each object, making it quite a useful feature. However, it does reveal the absurdity of some of the object descriptions which were probably cooked up in a hurry for release 1.0. For instance, the description for a Tenant object includes this:

For example, you can create a tenant with contexts and bridge domains shared by other tenants.

Oh really? Good luck trying to do that!!!!!

Tip for Cisco: Time to review the object descriptions in the Object Model.

Anyway, back at the fvTenant object, the old Pandora’s Box of information is still mostly there (I sadly miss the old Diagram section), some of it less clear than before, some of it more clear.

For instance, the old system had a great section on Naming Rules – nicely formatted with links to other name formats (you can see them underlined in the picture below. As you can see on the right, the new format is a) not formatted at all, and b) is missing the links.

Tip for Cisco: Keep the old style – codes like to see indents and good mon-spaced fonts, and coloured text always helps. Take a look at any coders editor for goodness sake! And keep the links.

One of the great features of the Old Style listing of the Naming Rules is that I could click on the word name above, and I’d be sent to the part of the page that shows the rules for tenant name, again well formatted and very clear to read.

From here I could easily see that a Tenant name has a maximum length of 63 characters and consists of only upper and lowercase letters, digits and the characters underscore, period and dash.

The good news is that the same information is not too hard to find in the new system either. With the fv:Tenant object still opened, I have several tabs I can navigate. The first one past the default Overview tab is the Properties tab and clicking on name gives me the same information. Not as succinctly, or as neatly as above, but there all the same:

And I really do have to call Cisco out on the choice of font again here. On the screen above I see the word:

Now – if any human can tell if the last 3 letters are double-l-d or double-I-d or Ild or lId then good for you – sure, the context probably reveals it, but this is a reference document.

Tip for Cisco: Stick with non-ambiguous fonts designed for coders when specifying names. It really does make a difference.

I do have one gripe with the Properties table in the new system. The old system also gave me a list of Constants that will be used – and I can’t find this list in the new system.

And this is important – without this information it would not have been possible to work out why a filter for TCP port 22 suddenly started allowing ALL traffic through! You can read about that disaster here.

Moving across the tabs, the Relationships tab has some key information right there, and this time with clickable links to the related object.

This is much more consumable than the older system, which did have the same information right under the diagram, but with the Relations separated from their corresponding object as shown above.

In the new system, Managed Object (MO) containments get thier own tab – and again, much more consumable, and with the list of Managed Objects shown in a more manageable (still almost never-ending) vertical list, but really, why someone decided to change MO (Managed Object) to Mo (a state in the USa) I can’t understand!

The remaining tabs (Faults, Events and Stats) are also presented slightly more nicely than the older version. In Events, for instance, the event Code is shown, whereas on the older version, you had to click the hyperlink on the event to discover the Event ID.

So what else is missing?

The most obvious omission in the new system is the massive diagram that accompanied the Object definition in the old system. For the sake of brevity, I’ve chosen one of the more manageable objects. Note that for each box in the diagram there is a clickable link under the diagram. The new system has the same MO information, but NOT the visual representation.

The other sections that missing (apart from the Constants mentioned above) are probably not as important. Those that need to delve deeper into the programming side of ACI may disagree, but the old system also had sections for Containers Hierarchies, Contained Hierarchy, and Inheritance. In some cases, (such as fvTenant above) the Contained Hierarchy list was thousands of entries.

My verdict?

I could find more missing pieces if I dug deeper, but I think I’ve covered the major items. But at the end of the day what Cisco has done is given us not just a prettier version, but in many cases more useable too. There are some important pieces missing, but I hope they will be added back in a future update.

Key advantages of the new UI

• Ability to filter on Configurable Only
• The search function is fast. Schmick!
• Tabbed interface is much neater and manageable than the old huge-html-page approach
• The pop-up window that appears when an object is clicked makes it easy to quickly browse through many objects/attributes and see the contained information.

Key disadvantages of the new UI

• Lack of attention to detail when it comes to presenting programming information. There are many typefaces/fonts designed specifically for programming, Cisco should use one of them.
  • Another example of the lack of attention to detail is the sudden translation of MO to Mo – it does make a difference. There could well be other examples too.
  • The CONSTANTS section needs to be shown for each relevant attribute
  • I’d like to see the Diagram section return, but I must admit I rarely used it.

RedNectar