JSON Structure and NSX-T

When is are {} not the same as []? To get a better understanding of JSON structure read below, or click the link in your Alexa app.

In NSX-T 2.4 the Policy API was introduced, which is a declarative API utilising a JSON structure. If you are unfamiliar with the Policy API, I recommend you read a number of great articles by my colleague Luca Camarda, starting with the introduction to NSX-T Policy API:

In this article I wanted to address the JSON structure itself, as it can be a little daunting the first time you look at it. JSON is a text-based data format derived from JavaScript, and is used in the API calls with NSX-T. Remember that with NSX-V we utilised the XML based format, but as of NSX-V 6.4 JSON was also introduced. In addition the NSX-T Policy API supports PATCH calls/method only. From a practical application perspective, this subtle nuance is important to understand.

So firstly, if using an application such as Postman how do we utilise this?

Excusing the toddler style handwriting 🙂 key point is to make sure you are making PATCH calls, and secondly the body of the text is sent in the JSON format. Anything else will return an error. CURL or other applications can be utilized, and I recommend reading Luca’s articles for further understanding on this.

So now we making our calls, what about the body of text we are sending. So in Luca’s articles he talks about how with NSX-T you need to make calls at the Infra level and then include your child elements, vs trying to write to the child node directly. So below I’ve included a bit of additional clarity on this.

Firstly we are going to implement a custom service and also a security group, without creating any associated firewall rules etc. The below diagram shows an extract of the Distributed Firewall data model for Policy API, and you’ll see that Service, is a child element under Infra, and Groups is a child element under Domain, which in turn is a child element under Infra. Understanding these relationships is key to successful policy API implementation.

So now let’s look text to create a service call.

1. Firstly note we are making an API Call at the Parent Level – Infra
2. Then we denote our children, of which an element includes ChildService

The key point here is the word Child in front of Service. As you denote each child element it will always have the child suffix. So now let’s look at something a bit more complicated, the Group creation API call:

Anyone else looking at this and thinking …. OMG !!!

Let’s break it down it’s not that complicated really, but the important thing to understand is importance of the {} brackets vs the [] brackets.

JSON defines only two data structures: objects and arrays. An object is a set of name-value pairs, and an array is a list of values. JSON defines seven value types: string, number, object, array, true, false, and null.

I highlighted array in the second statement, as an object value can be an array.

JSON has the following syntax.

• Objects are enclosed in braces ({}), their name-value pairs are separated by a comma (,), and the name and value in a pair are separated by a colon (:). Names in an object are strings, whereas values may be of any of the seven value types, including another object or an array.
• Arrays are enclosed in brackets ([]), and their values are separated by a comma (,). Each value in an array may be of a different type, including another array or an object.
• When objects and arrays contain other objects or arrays, the data has a tree-like structure.

Reference: Introduction to JSON by JavaEE

So back to to the Group API call (image 4), we have one big Object that consists of multiple name:value pairs, as well as an array of other objects. The Below diagram helps to map everything out.

From the diagram you can see that making a group requires you to reference the Infra Parent entity, and then its child entity Domain, and finally Domain’s child entity Group. So our API call structure is correct. Next we need to understand what the {} and [] are all about. So referencing the numbers in the diagram:

1. The opening { denotes that we are creating an object with multiple name:value pairs. The resource type s infra and it has multiple children.
2. The [ supports the statement multiple children in the above sentence. An array allows us to list multiple values, of the seven types. Which can include other objects and arrays. So here I have an object that has it’s first name:value pair being resource_type:infra, and it’s second name:value pair being children:[an array of multiple objects]
3. we now have our first object, which is referencing the Domain Child entity. Now for the sake of this example I have separated out my Domain and Service entities at this level, but I could absolutely have multiple child entities at this level. In Luca’s articles he demonstrates this.
4. The Domain object has an array value
5. We state Domain’s name:value pairs and then it’s children, of which we are creating Groups. Again, we could include the Security Policy child element, but for the purposes of this example it’s been left out. See Luca’s posts for further details on this.
6. The first object is the Domain’s child Group. This is then documented with it’s associated configuration, which consists of multiple name:value pairs, of varying types.
7. We then close out our first group object, but with the , denoted we are going to create additional Groups.
8. We then denote our second object in children part of the Domain object
9. Here we stipulate the next group we want to create

So hopefully you can see that though it looks a bit complicated, ultimately we are creating objects, and where an object can have multiple name:value pairs or other nested objects we start to use arrays.

For those of you new to JSON and Policy API, hopefully that’ll help with structuring your API calls, and being successful with Policy API.

Bal Birdy

VMware by Broadcom

Bal is an Open Group Certified IT Architect, and VCDX #269, specializing in the network and security arena, with over 15 years experience in enterprise level network/system technologies. His goal has always been to maintain a holistic view of the architecture allowing him to understand how various technology streams may impact the networking/infrastructure space.
Bal has a proven record of delivering on enterprise network designs, leading data center and site migrations as a result of business mergers and acquisitions, and vendor migrations e.g. Cisco to Checkpoint/Juniper. As part of this he worked across several business sectors: Utilities, Banking, Retail and Government, and can base designs around sector specific standards e.g. PCI-DSS, DSD and ISM. He is proficient in several technology areas including Cisco, Juniper, F5, VMware, Citrix and Microsoft. These skills are supported by non-technical certifications: Prince2 Project Management Practitioner, ITILv3, TOGAF 9.1 Certified and Open Group Certified IT Architect – Open CA.
In addition to supporting the Livefire Team, Bal leads several innovation efforts within the VMware WRACE organization, including projects investigating the use of Virtual Reality/Augmented Reality, AI/ML and Interactive 360, to support customer and partner enablement.

Certifications:
BSc (Hons) Computer Science
CCNP/CCDP
VCDX-NV #269
Open Group Certificated Architect
Member of the Associated of Enterprise Architects