Using a #REST API in the virtualization field: An introduction to REST (#VMworld edition)

In the modern era we observe more and more solutions offering a RESTful Application Programmable interfaces (API) that can be accessed by users or other systems in a standardized and clear defined way.

Within the datacenter all kind of resources are offering functionality via APIs. Viewing, configuring, deleting network functionalities, storage capabilities gives us the opportunity to automated nearly everything within our datacenter. Standardized APIs are the key-element of the Software-defined datacenter.

rest

Standards within the application world helped us to create a common language. Working in the VMware we can stumble daily about two different instantiations of those APIs

  • Simple Object Access Protocol (SOAP): among others offered by vSphere / vCenter.
  • Representational State Transfer (REST): among others offered by vRealize Operations, Orchestrator, NSX Manager and specific vCenter Services

During VMworld Europe 2016 VMware gave us insights about the new RESTful API of the vCenter Server. Please check out Chris Wahl’s fantastic blog post on this topic.

Understanding RESTful APIs and how to deal with them is getting more and more important. Having worked with the new Access Point of VMware Horizon (for View, Identity Manager, Airwatch) I realized VMware’s dev team somehow missed to create a suitable User Interface (UI) and just created a REST API to do all the installation and configuration (tbh: I hope that this not a new trend coming up)

Since more and more solutions are offering a REST API I want to give you some further insides and background about REST and how we can use it (interactive & automated) within our environment.

REST in general

So let’s get started about the characteristics of a RESTful API  (there is no concrete implementation definition for REST). REST relies on a client / server architecture. The focus of REST is more related on things instead of functions and methods.

This thing is a stateless resources identified via an URI represented via JSON or XML.

…… Can you repeat that 3 times in a row?!

Honestly this sentence does not really help us understand REST a little bit better, so let’s break it up (divide and impera)

A REST API gives us access to a resource within a client / server architecture:

In general: The server delivers a representation of a resource to a client

Concrete: The NSX Manager (Server) delivers a logical switch (resource) representation  to a RESTclient installed on a Users Desktop (Client)

Resources within REST are identified via an Uniform Resource Identifier (URI )

In general:  The representation of a resource can be access via the URI: https://whereeveritis.com/api/Resources

Concrete: To access a Logical Switch within NSX you need to identify the specific switch. The representation of the switch can be found at: https://NSX-Manager-IP-Address/api/2.0/vdn/virtualwires/virtualWireId

Rest is based on web standards:

In general: Resources are delivered via standardized formats like JSON or XML (content-type): e.g. Successfully calling the above mentioned https request leads to a logical switch representation in the following format:

Concrete:

<?xml version=”1.0″ encoding=”UTF-8″?>

<virtualWire>

    <objectId>virtualwire-11</objectId>

    <objectTypeName>VirtualWire</objectTypeName>

    <vsmUuid>423BAFC5-2101-5BF5-16E5-F44F7B0EFE9E</vsmUuid>

    <nodeId>73188b36-93d8-4310-a4c9-3a25bdadc590</nodeId>

    <revision>3</revision>

    <type>

        <typeName>VirtualWire</typeName>

    </type>

    <name>Web-Access</name>

    <description></description>

    …..

    <vdnId>5000</vdnId>

    <guestVlanAllowed>false</guestVlanAllowed>

    <controlPlaneMode>UNICAST_MODE</controlPlaneMode>

    <ctrlLsUuid>612858eb-406c-405e-9cd9-a1c724792fe0</ctrlLsUuid>

    <macLearningEnabled>false</macLearningEnabled>

</virtualWire>

In general: Using XML or JSON helps us to access and process the gathered information easily in a programmatic approach. Almost every programming language has serializing methods to gather data out of the represantion.

Concrete: Powershell offers us the opportunity to use the standardized query language XPath within Powershell:

Storing the earlier mentioned XML outcome into the $xmlInput file we can use the following snippet to access the name of the logical switch.

$xmlInput | Select-Xml -XPath “virtualWire/name” | Select-Object -ExpandProperty Node

#text
—–
Web-Access

Learn more about XPath at the W3School.

In most implementations REST is used via http(s). The http(s) standard has integrated methods (GET, POST, DELETE, etc.) that are used to manipulate the resource we are accessing:

e.g. DELETE https://NSX-Manager-IP-Address/api/2.0/vdn/virtualwires/virtualWireId

The last characteristic of REST has to do with statelessness. Talking about modern applications the term statelessness comes up all of the time, but what does that mean exactly? Within the REST world it is important to know that the server responds in a stateless manor. Every single request we send to the server can be answered without knowing what happened before or will happen afterwards.

But still many applications rely on a specific statefulness. Within a REST architecture it is the responsibility of the client to maintain the state of a specific application.

The statelessness on the server side is quiet a limitation, but at the same time it is a way for application builder to create a scale-out-able application as well. We can get information about a resource on Server01 and manipulate the resource via Server02.

Let’s come back to my tongue-breaker (I guess that’s a pure German translation):

This thing is a stateless resources identified via an URI represented via JSON or XML.

NOOOOOW it makes sense (at least I hope so).

In the next part I am going to demonstrate the usage of REST with Curl, Chrome REST clients and Powershell.

Leave a Reply

Your email address will not be published.

Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.