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

In the previous article 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"


DTG-019.png


After a few seconds the first screen will appear.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-020.png

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.


b_600_0_16777215_01_images_phocagallery_tutorials_DTG-021.png

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.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-022.png


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)


DTG-023.png

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.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-024.png



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

DTG-025.png

We now get an array [] of vnics objects {} under .vnics
Click next and use .vnics as objects selector, press tab

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-026.png

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.

DTG-027.png

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


As expected all properties are listed, including the mandatory name property but missing the id property. Click Insert value.
DTG-029a.png

Use id for property and .index for accessor
DTG-030.png

The validation error disappear and the properties preview is populated. Click next.
b_600_0_16777215_01_images_phocagallery_tutorials_DTG-031.png


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.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-032.png

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

DTG-033.png


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.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-034.png


Click next. As before the id property is missing.

b_600_0_16777215_01_images_phocagallery_tutorials_DTG-035.png


Edit the properties accessors input and insert a new value

DTG-030.png

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


b_600_0_16777215_01_images_phocagallery_tutorials_DTG-036.png


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.

DTG-037.png

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


Unfold the namespace / host / edges.

DTG-038.png

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:

DTG-039.png


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

NUC Lab Kit

Below are my thoughts for a vSAN nuc lab. Since I already have cables, not including them here. I ordered (and received by Nov 30, 2016)
3 x nuc, 3 x 32GB Crucial mem, 3 x Toshiba NVMe drive, 3 x Startech USB to GB NIC, and 3 x Crucial 1TB SSD. I've also been very happy with my Cisco SG300-10 so I bought one more since my existing one only has one port available. Each of the items listed here are linked below - all were purchased using the provided links below.
single NIC (See this post for details on using the USB -> GB NIC item listed below

I stayed with the i5 for the power consumption and form factor vs. the i7 Skull Canyon ;)

 

Search

Experts Exchange