Postman + vRO = HTTP-REST Plug-in Operations

In a previous article, I stepped through the process of working with vRealize Orchestrator's (vRO) REST API using the RestClient add-on for FireFox. This was before I was introduced to my new favorite REST client: POSTMAN! (@postmanclient) In this article, I'll provide a little detail on an approach you can use to improve your work with REST APIs and consuming them with Orchestrator's REST plug-in. Throughout the article, I will use a FreeNAS 9.3.x Virtual Appliance as my target endpoint since it is freely available, quick to setup, and has nice API documentation. Please note that the technique described here can be used for any API that Postman can access!

Environments

environments.png

Postman has a cool feature that allows you to define variables called Environments. This is important with the work we do around Orchestrator as you may have a local and remote instance (or test/dev and production) of a system you wish to automate. By defining an environment variable, you can create a Collection of API Requests that can target different environments by simply selecting the environment before clicking Send when testing.

Create an Environment for the API you wish to work with. In my case, this will be for my Local FreeNAS Appliance. For the "Key" field, give it a meaningful name - I chose "freenas-api" for mine. In the value field, check your api documentation to get the root address of the API. In the case of FreeNAS, this is http://freenas-host-address/api/v1.0 so that's what I'll specify here. Throughout the rest of the documentation, calls for various information assume this address to be the root so give an address like /sharing/nfs/ to get a list of NFS Shares. Defining your API root address this way will make it easy to build your collection of API calls in a consistent format with the documentation.

Collections

collections.png

  1. Create a new Collection, I named mine "FreeNAS". This will allow you to create a "collection" of calls for a specific service, which you can then later export....
  2. Set the Environment by clicking the drop-down at the top of the screen, in my case, I chose the "FreeNAS Local VA API"
  3. Specify the API endpoint you wish to perform and operation against, making sure to use the Environment Variable you created earlier for the base address of your api. Based on the documentation, my freenas-api variable should be formatted as {{freenas-api}}. Then, add the rest of the address. In my case, I wish to list the NFS shares. According to the documentation, this is accessed via /sharing/nfs/
  4. Next, set your Authorization as needed by using the "Basic Auth" tab. (Note: In some cases, you can simply try to perform an operation and you will be prompted for credentials. Additionally, you may need to open a Chrome browser tab to the address you are attempting to access in order to accept SSL Certificates - particularly in the case of Self-signed or invalid certs).
  5. Add any Headers (if needed) by clicking the Headers button, then adding them, and select your operation type. In my case, I selected and clicked "GET"
  6. Now, review the output of your operation. In my case, I see that there is one NFS share available.
  7. Once you have adjusted your query so that it produces the desired results, click the "Add to collection" button

NOTE: When defining your URL, BEFORE adding to collection, place any url parameters inside curly braces. For example, if I had an operation to Delete an NFS Share, I would need the share ID:
{{freenas-api}}/sharing/nfs/{nfsId}

When testing the above DELETE command in Postman, I would need to replace {nfsId} with "1" to delete the "My Test Share" shown in the screenshot above. But, by adding to the collection in the format I have provided here, it will be meaningful to Orchestrator when you Invoke the operation. When invoking an Orchestrator RESTOperation that has such a value in the url, that value is interpreted as an input!

Add request to a collection

add_request_to_a_collection.png

  1. Select the Collection you created earlier from the Existing collection drop-down or create a new one if needed.
  2. Provide a short, meaningful name, and optionally a description
  3. Click Add to collection

Continue building your collection

continue_building_your_collection.png

Now, repeat this process by testing and adding the various calls to the API that you need.

Export the collection

export_the_collection.png

When you are done, click the Share collection link as shown in the image above.

Download collection

download_collection.png

Click the Download button to download the JSON file that holds your entire collection. You can find my Postman Collections on Github, as of this writing, only FreeNAS.json is there.

Online JSON Tools

online_json_tools.png

When working with JSON, it's good to have a few sites bookmarked or tools available. Here are a couple I use frequently:
JSONLint <- Great for quick JSON validation
JSONViewer <- Nice all-around tool that lets you visualize your JSON in a tree view (Screenshot shows the viewer pane)

Orchestrator: HTTP-REST Plug-in

orchestrator_http-rest_plug-in.png

Now that you have your collection tested and exported, head over to your Orchestrator server and add a new host to the HTTP-REST plug-in.
When specifying the URL, be sure to use the same value specified when you defined your environment variable. In my case, this is: http//freenas/api/v1.0

Operations?

When you have only one or two HTTP-REST operations to define, this can be done quite easily in a manual fashion by using the workflow: Add a REST operation
However, if you've been building up a large collection of operations in Postman, replicating all that work into Orchestrator's REST Plug-in in the form of Operations may not be desired..

Orchestrator Workflow: Process Postman Collection

orchestrator_workflow_process_postman_collection.png

The "Process Postman Collection" workflow I have written makes this a piece of cake! Since Postman has kindly provided us a json formatted file, this is easily processed by Orchestrator!

Workflow Inputs

workflow_inputs.png

Simply provide the json file you exported from your collection and the RestHOST you created for your input and click SUBMIT!

Workflow Run

workflow_run.png

The workflow will extract the requests from the json, then add each one as a REST Operation.

Check out your HTTP-REST Inventory now!

check_out_your_http-rest_inventory_now_.png

As you can see, the workflow has taken the Name, method, and URL from the json and created a REST Operation under the specified REST Host.

RESTOperation Details

restoperation_details.png

Each operation may now be reviewed/tested or used via workflows/actions!

Next Steps:

Grab the workflow and add features to it! You could potentially:

  • Update the workflow so that it checks for existing operations before adding one and skips if already exists. If you run this workflow twice, you'll end up with duplicate entries for every operation
  • Update the workflow so that it UPDATES existing Operations if they already exist rather than creating duplicates or simply skipping them
  • Combine the previous 2 bullet points so that you can specify whether you wish to update existing operations or just skip them
  • Update the loop so that it generates workflows for each operation once the operation has been defined
  • Change the workflow to prompt for Endpoint details so that it creates the RESTHost, then adds the operations to the newly created host
See the NEWLY ADDED (Sep 14, 2016) attached workflow from one of my co-workers and blog followers that adds many of these additional features!

As you get comfortable with the structure of the calls, you can clean-up and optimize them OR generate a single call capable of handling multiple different actions! This is the approach taken by Christophe in the Dynamic Types Plug-in Generator :)

In addition to the Process Postman Collection workflow, I have also attached a Clear Operations workflow that will allow you to quickly and easily DELETE all RESTOperations from a given RESTHost. This may be important if you are testing or made a mess. Of course you could always just delete the RESTHost and all attached Operations will be automatically deleted.

UPDATE: Be sure to take a look at Grant Orchard's collection noted in his article here:  Postman Collection for the vRA7 API 

Attachments:
Download this file (Process Postman Collection.workflow)Process Postman Collection (Right-Click to save!)[Right-Click on file and choose to save as - be sure extension is .workflow]9 kB

Comments  

+1 # TeamBanners 2015-09-26 07:57
:lol: This really answered my problem, thank you!
0 # Olaf 2015-05-27 21:15
Thanks for the quick response Burke.
Downloaded the updated workflow and it works!
0 # burke 2015-05-27 14:35
This article received a couple updates today:
  • Link to my postmanCollecti on repo on Github
  • Updated workflow AND Clear Operations workflow
  • Updated Next Steps section by adding NEW first 3 bullets
+1 # burke 2015-05-27 13:34
Quoting Olaf:
Great post!
I do have one small remark.
Imported the Process Postman Collection workflow in my vCO 6.0.2.1 appliance and noticed that the action addRestOperations is not present. Also looked at a vCO 5.5 which does not have it either.
Is this a custom action that needs to be created?

Hmm.. Nice catch! Looking into that now... darn, I had used a custom action while testing and forgot to change back to library workflow. Please download updated workflow.
0 # Olaf 2015-05-27 13:19
Great post!
I do have one small remark.
Imported the Process Postman Collection workflow in my vCO 6.0.2.1 appliance and noticed that the action addRestOperatio ns is not present. Also looked at a vCO 5.5 which does not have it either.
Is this a custom action that needs to be created?
+1 # Ivan Krolo 2015-05-20 22:28
Fantastic work Burke!

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