[personal profile] ladquin
Picking up the general topic from the previous post, it's time now to get more specific. Currently I'm working on the API docs' bug backlog, which goes from fixing errors and updating current data to adding support to new extensions to the OpenStack API Reference site.

OpenStack has developed a wide and still growing collection of RESTful APIs, which are sets of functions and specifications that provide the users and administrators with a simple and lightweight interface to interact with other complex systems or libraries, such as the different components of the cloud computing environment:


So I had this vague idea of what an API was and what it was used for, but the term "RESTful" was new to me. Given the latter and the fact that the following info is available more extensively and accurately browsing the web, I'll try to keep it simple, mainly for other "uncultured" like me.

REST stands for Representational State Transfer, and while it's an architectural style for Web services, it is not a standard. That's perhaps the reason why today any API is easily (but sometimes wrongly) called RESTful. The term was first utilized by Roy Fielding, who's one of the authors of the HTTP protocol.
Despite not being a standard, there are good practices to consider and, furthermore, there are constraints that define the basic qualities of the RESTful style. The six constraints are: Uniform Interface, Stateless, Cacheable, Client-Server, Layered System, Code on Demand (optional).
I will not describe them here, as they possibly deserve an exclusive post, but if you're really interested you can read Fielding's dissertation, which is the original source. It would be interesting instead to mention the goals of this type of architecture, which sound quite familiar:
  • Scalability of component interactions
  • Generality of interfaces
  • Independence of components deployment
  • Intermediary components to reduce latency, enforce security and encapsulate legacy systems
I found it not surprising that OpenStack had chosen this API model. I've gone through several docs and links, but the best explanation of how this design model works without being terribly complicated was found in this tutorial (also found this one, a bit more orthodox, but you can fork it in GitHub!):

"...The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.
RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations."

Here's a slightly modified example of how a RESTful API works in OpenStack:
 
 

The user sends a HTTP request, using the GET method, to the API. In order to do that, the user will need the API's URI (Uniform Resource Identifier, which is a string of characters to identify a resource, i.e.: "http://hostname:port/v2.0/users").
The API relays the request to the final system, in this case Nova (or Compute Node), which will process the request and send back a message (response) through the API to the user.
This is rather a simple example of how it would work, but there are others in which you'll also need to provide a request body in JSON or XML format (Openstack APIs support both). Response bodies, if available, will also be returned in those formats.  The HTTP methods to use, depending on what you need to do, are GET, PUT, POST and DELETE.

The way to interact with a RESTful API is up to the user: many at OpenStack use cURL, which is a command line tool, and will be maybe the best option if you're comfortable with text terminals.
A request to list all the IP addresses of a server will look like this on cURL:

$ curl -v -H "X-Auth-Token:XXXXXXX" http://localhost:8774/v2/openstack/servers/1/ips

... and this is what you'd get in response (JSON format):

{
"addresses": {
"public": [
{
"version": 4,
"addr": "192.168.100.2"
},
{
"version": 6,
"addr": "fe80:0:0:0:0:0:c0a8:6402"
}
],
"private": [
{
"version": 4,
"addr": "192.168.200.2"
},
{
"version": 6,
"addr": "fe80:0:0:0:0:0:c0a8:6402"
}
]
}
}

If you prefer a graphical interface, there are several to choose from, like the Firefox RESTClient (it's an add-on):


_________________________________
 
OK... perhaps I've rambled too far without going very deep in many of the subjects of the post: some of them are so relevant to today's software architecture that probably being exhaustive could take too long, but the idea was to remain simple, as much as I could.

Although far from "restful", I feel the research on all these concepts has given me a better understanding of what I'm documenting and why it matters.

April 2013

S M T W T F S
  123456
78910111213
14151617181920
21222324252627
282930    

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Oct. 2nd, 2014 04:20 am
Powered by Dreamwidth Studios