Getting Started with the vShield API

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:

• https://www.vmware.com/pdf/vshield_410U1_api.pdf
• http://www.infoq.com/articles/rest‐introduction
• http://www.infoq.com/articles/rest-anti-patterns
• http://www.stucharlton.com/blog/archives/000141.html
• http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.htm
• http://rest.elkstein.org - Learn REST: A Tutorial
• http://oreilly.com/catalog/9780596529260 - RESTful Web Services
• http://jersey.java.net - Jersey is the open source, JAX-RS (JSR 311) Reference Implementation for building RESTful Web services
• http://restpatterns.org/HTTP_Status_Codes - HTTP Status Codes