What’s this REST thing everyone keeps talking about?

“Oh, don’t worry, we have a REST API.”

or

“It’s just a simple REST call.”

At one point I was hearing these phrases and would get very frustrated. If REST is so commonplace or so simple to use, then why did I not know how to do it? If this sounds like you, then keep reading. I work for a company called “Ahead” as a consultant and they recently got a Rubrik Hybrid Cloud Appliance in their lab but my colleague Nick Colyer and I noticed that they didn’t have any vRealize Orchestrator Plugins for it. We decided to build these on our own, with the help of Chris Wahl and publish them for the community to use.

This post is the beginning to a series about building vRealize Orchestrator (vRO) plugins to connect to a Rubrik Hybrid Cloud Appliance via their built in API. Hopefully after reading the series you can see how Nick and I wrote the vRO plugins that you can freely download from Github.com

REST

OK, lets start with the basics. REST stands for “Representational State Transfer” and is a way to pass information between systems. A RESTful API consists of a host, a resource, a method, headers and the payload.

Host

This one is easy to understand. It’s a server that requests will be sent to. REST isn’t magic and needs to know what server in which to send its commands, just like any other type of client-server communications. Generally this is done over HTTPS connections and https://rubrik.local:443 might be a valid host if your rubrik appliance is named “rubrik.local”.

Resource

The resource identifies a “thing” you’re trying to access information from, or action you’re trying to perform. For instance, with Rubrik, we can view the virtual machines by accessing the /vm resource. If we combine the resource with the host, we will get “https://rubrik.local:443/vm.”

Method

Methods are the actions that can be performed. There are several well defined methods that can be used such as:

• GET – Read information
• PUT – Write Information
• POST – Perform an action once
• PATCH – Modify Information
• DELETE -Delete Information

For example, if we wanted to list all of the VMs in the Rubrik array, we would use a “GET” on the resource https://rubrik.local:443/vm.

Headers

Headers are used to format the requests and the responses. For example, the header commonly includes authentication information as well as a format that the communication will be presented. Many times data is passed as a JSON object but it could be passed as XML or a string. The header will identity what format this information will be passed.

Payload

The payload is a generic term for “the data” that you’re trying to pass between systems. This could be, “nothing” all the way over to a large array of values. In the “GET” example earlier there isn’t a payload, but if we did a “PATCH” operation we would have to pass some information about what settings we plan to change.

Using Rubrik’s Swagger-UI

Luckily, if you’re new to APIs, Rubrik uses a framework called “Swagger-UI” which is open source and shows you how to execute all of the APIs. There are examples for all of the operations. For instance, below, you can see the “Login” resource and the “POST” operation.  From the screenshot, you can probably also tell that it requires a “userID” and “password” in the request and the header will request responses in the type of “application/json”.  The swagger UI is a really nice way to visually see the API and really helps to get started.

Summary

The REST operation will be a crucial piece to our communications between vRealize Orchestrator and the Rubrik appliance so its important to understand the basics of REST before we dive into the plugins that Nick and I created. If you want to just get the plugin and work with it, I urge you to check out Nick’s posts over at SystemsGame.com for details on how to use the plugins. The “rest” of this series will focus on how we built the plugins and the REST operations needed to make the plugins work.

The next post will focus on setting up our REST hosts and operations for the Rubrik appliance so that we can run some commands.