Create a plug-in for a REST based web service in minutes - Part 2

In the part 1 I walk through step by step to create a plug-in object type leveraging the Plug-in Generator version 2.

In this article I will demonstrate one of the new feature of this version 2 : Create a child object type.

Having the plug-in inventory organized in a tree view allows to represent most of the objects hierarchies found in applications APIs.

Resuming from part 1 I need to create a vNIC object. It does not make any sense to list all the vNICs objects under the NSX host since each edge has up to 8 vNics that may have the same name.

The API guide provides the

GET https://<nsxmgr-ip>/api/4.0/edges/<edgeId>/vnics

that shows that a vNIC is obviously under an edge object.

In the type hierarchy right click on edge / Run “Plugin gen -3- Create a type”

After a few seconds the first screen will appear.

Enter a type name, select an icon, enter a proper folder name. Click next. Select the host you will interact with for the requests. Click next.

While this is optional this time we will select to use a findBy ID URL as well. This will reduce the number of requests done and increase performance.

The find relation URL is adapted from the API guide https://<nsxmgr-ip>/api/4.0/edges/<edgeId>/vnics

  • No need to include the https://<hostname>
  • The parameter has to be in curly brackets {}
  • The parameter name must be a type you defined

Note that validation will be done on the URL, the parameter name and order.

Once you will have entered the URL and hit tab the list of available edges should be listed for the parameter 1 field.

Copy and paste the response to a JSON viewer (I.E http://jsonviewer.stack.hu)

You can see that the result is not the vnics objects we were expecting but an error object. In this particular case the edge-1 is not supporting the /vnics API since the edge is of type distributedRouter.

Switch Parameter 1 to another edge.

This will update the response. Copy and paste the response to a JSON viewer

We now get an array [] of vnics objects {} under .vnics

Click next and use .vnics as objects selector, press tab

Copy and paste the response to a JSON viewer. Now we got the vnics properties. Note there is not an id property but an index one.

Click next.

Since the object is missing the mandatory id property the workflow validation will raise an error. Click on the properties selectors input.

As expected all properties are listed, including the mandatory name property but missing the id property. Click Insert value.

Use id for property and .index for accessor

The validation error disappear and the properties preview is populated. Click next.

Since we chose to use a findById URL to get better performance in the plug-in we get to another round interacting with the target server.

  • The URL is the same as the one we used for findRelation except is has the extra /{vnic} to get a single vnic. The name of the last parameter must be the same as the type name we defined on the first screen. Otherwise you will get a validation error.
  • The parameter 1 must be again set to an edge different form the edge-1 since it does not support the /vnics API
  • The parameter 2 can be any of the configured NICs. While the non configured NICs are listed as well a configured NIC will provide a better response sample.

You can copy and paste the response in a JSON viewer to check the properties. You can notice the JSON contains directly the object properties without any intermediate object.

Click next. This time there is nothing to do since there is no need to enter the path of the properties in the object accessor input.

Click next. As before the id property is missing.

Edit the properties accessors input and insert a new value

Use id for property and .index for accessor. The properties preview should now be populated. Click next.

Since we are getting object properties from two methods / URLs we may get different properties (it seems like bad design but believe me it does happen !).

This last screen defines the properties of the object you are creating.

Intersecting properties will only use the ones that are common for the different methods. Merging properties aggregate them (in this case they may not be filled depending which method is called).

To prevent from having properties discrepancies there are a few workarounds:

  • If you see different properties names get the same property values rename them when defining the properties accessor so they can be intersected
  • You may use your own action (this will be the subject of another article) to create get properties programmatically. This offers a lot more flexibility
  • If performance is not an issue (small set of objects) and if the URL you define in findRelation gets the property you need only define findRelation

In the case of the vnic it does not matter since the properties are the same when getting all vnics for an edge (FindRelation) or when getting a specific one (findById)

Submit your workflow. Click run in background.

Check your type hierarchy.

You now see the vnicFolder and vnic under the edge type.

Unfold the namespace / host / edges.

You now see listed the Nics folder that has objects under the second edge in my case but not the first one (This was the one where the edge of type distributed router did not support the /vnic API - if you need these you need to go through this workflow again using /interfaces at the end of the URL).

So basically with following the part 1 and 2 of this plug-in generator series you should be able to create your own plug-in inventory using the plug-in generator “Create a type workflow”' and eventually get to something like this in a couple of hours:

In the next part we will see how to create, operate, delete the objects we have in the inventory.