Home > Blogs > VMware vCloud Blog


Getting Started with the vShield API

By: Michael Haines (Senior Cloud Security Architect)

In order to best explain how to get started using the vShield API, we’regoing to introduce a hypothetical example of an implementation using a traditional Network and Security System Administrator at the company,“Example Systems.” This is the first in a five-part blog series on usingthe vShield API.

The Network and Security System Administrator has found out that Example Systems intends to turn their Tier-1 Application into a business offering to multiple organizations and now needs a way to repeatedly and rapidly deploy the same application every time a new customer comes online. To help with this the Network and Security System Administrator intends to use the vShield REST API's to rapidly provision security.

But before the Network and Security System Administrator can begin to use and work with the vShield REST API they need to understand some of the basic principles about REST and vShield API.

  • The vShield Manager requires ports 80/TCP and 443/TCP to be open for the vShield REST API requests to pass through.
  • All vShield REST requests require authorization. You can use the following basic authorization: Authorization: Basic YWRtaW46ZGVmYXVsdA== (I will cover this in more detail in the following lessons).
  • There is no login required as in other similar REST based applications.
  • The Network and Security System Administrator will need to use the vShield REST APIs to determine the mo-refs Id of the VI managed Objects like datacenter, cluster etc.

——–

When the Network and Security System Administrator has successfully implemented the security policy and security architecture using the vShield products, they will want to start looking at how to use and implement the vShield API.

This section of the blog introduces the Network and Security System Administrator to the VMware vShield API. In these series of blogs the Network and Security System Administrator will get hands on programming experience with the vShield API and learn how to consume the API in their own programs and applications. The Network and Security System Administrator does not need to be a developer, although basic programming concepts will help them understand the vShield API better.

An introduction to the vShield REST API, and some of the background concepts for Network and Security System Administrator's can be found at the end of this post. Feel free to forward to the end and read the basics before proceeding if you are completely new to programming.

The vShield REST API uses HTTP requests (which are often executed by a script or other higher‐level language) as a way of making what are essentially remote procedure calls that create, modify, or delete the objects defined by the API. This vShield REST API (and others) is defined by a collection of XML documents that represent the objects on which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients.

The vShield REST work flows fall into a pattern that includes only two fundamental operations:

1. Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a well‐known URL (such as the vShield Manager) or a link obtained from the response to a previous request. 

2. Examine the response, which can be an XML document or an HTTP response code. If the response is an XML document, it may contain links or other information about the state of an object. If the response is an HTTP response code, it indicates whether the request succeeded or failed, and may be accompanied by a URL that points to a location from which additional information can be retrieved.

Special thanks to Kaushal Bansal, Sr MTS at VMware for all his help and support. In our next blog, we will introduce the Network and Security System Administrator to Automation tools with vShield App for scalability through REST APIs. Be sure to follow @vCloud and @VMwareSP on Twitter to catch the next post in this blog series!

For better context:

A More In-Depth Look at REST

Definitions:

REST Representation State Transfer

  • REST is an architecture design for building that loosely couples services, highly scalable and can use HTTP protocol.

Resources

  • A resource is anything that is identified by a URI. Although this appears to be a circular definition, there is no formal definition of what might be a resource. It can be anything.

Representation

  • A representation is an encapsulation of the information (state, data or markup) of the resource, encoded using a format (e.g., HTML).

HTTP HyperText Transfer Protocol

  • HTTP is based on a request and response synchronous communication; it is stateless, distributed and very scalable.

URI Uniform Resource Identifier Uniquely identify a resource on the server which provides a service

  • A client such as a web browser sends a request to a server using one of four methods and expects some service performed. The methods are POST, GET, PUT and DELETE.

REST stands for "Representational State Transfer", which may make things less clear to understand. So, instead of trying to dissect what this means, let us consider a simple web based application, something you do everyday.

1. (client) User goes to the home page and clicks a button.
2. (client) The browser submits an HTTP request to the server.
3. (server) The server send back a responds with an HTML document containing some links and forms for example.
4. (client) User fill's in a form and submits it.
5. (client) The browser submits another HTTP request to the server
6. (server) The server processes the request, and responds with another page.

The above exchange will continue until you stop browsing. Except for a few exceptions, most web sites and web based applications follow the same logic.

Let's take a closer look, and see how this is related to REST. 

Putting it all Together 

The key concept here is of a stateless client-server architecture where clients send requests to servers, which in return send back responses. Pretty simple, eh? Rather than the client and the server maintaining state, the state is transferred in the requests and responses. This is what "representational" means, in that there is some representation of the state exchanged between client and server. There are a number of things that REST architectures impose. If you adhere to these constraints, your architecture is considered RESTful (I will discuss this a little later). It just means that your architecture obeys the REST constraints.

REST is not new, but it has become in-vogue fairly recently. Basically the entire web is built on REST concepts. Every time you click a button on a web page in a web browser (client) you're sending a request to a web server, which in turn sends back a response. This does not mean that all web services are REST-based, of course, just that they share some of the characteristics. A good example of a RESTful application is Google Mail. When you log into Google Mail, it sends a request to get the contents of your inbox (actually the latest n messages). The Google Mail server sends back a *representation* (the R in REST) of your inbox, which the client displays. You can then click on a message to read it, which sends a request to the server for the contents of the message. Actually, it's a little more complicated than this, since Google Mail can be doing things behind the scenes while you are reading messages. The point is that the Google Mail server has no idea which set of messages you are reading or which message is currently displayed. It keeps no state (i.e., it's "stateless".)

If it helps, you can consider the client being "at rest" when it's not actively engaged in communication with the server.

Also note that RESTful architectures do not have to be based on the HTTP protocol. You could implement them over any protocol you like. It's just that typically, HTTP is what RESTful implementations are based on.

Note carefully the list of 6 Constraints.

Summary

In this short background, I have attempted to provide an introduction into the concepts behind REST. A RESTful HTTP approach to exposing functionality is different from RPC, Distributed Objects, and Web services, it takes some mind shift to really understand this difference. Being

Objects, and Web services, it takes some mind shift to really understand this difference. Being aware about REST principles is beneficial whether you are building applications that expose a Web UI only or want to turn your application API into a good Web citizen.

More REST References and Resources:

There are many sources of information about vShield and REST, here are a few to get you started: