Introduction to the CloudStack API

Sebastien Goasguen@sebgoa

Outline

• Documentation• Clients• Exploration• Integration port• Signing requests• REST or not REST

Documentation

http://cloudstack.apache.org/docs/api/apidocs-4.0.0/TOC_Root_Admin.htmlhttp://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/API_Developers_Guide/index.html

Clients

• 15 clients and counting… on Github

• Java, Python, Perl, Ruby, C#, php, Clojure

Exploration

• Use a debugger console• E.g Firebug• As you navigate the UI,

check the http calls that are being made

• Identify the methods• Identify the parameters

passed to each call

HTTP based

• API calls made via HTTP(s)• Pass name of the call as command• Pass list of key/value pairs as arguments to

the call• GET method• Response can be XML or JSON• Query API that is RESTlike

http://gehrcke.de/2009/06/aws-about-api/

Integration Port

• Unauthenticated call– Dangerous– Don’t open it all– Certainly don’t open it to the public internet

• Set the port on the UI

Using the integration port

http://localhost:8096/client/api?command=listUsers&response=jsoncurl 'http://localhost:8096/client/api?command=listUsers&response=json'

{ "listusersresponse" : { "count":3 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg”…

http://localhost:8096/client/api?command=listUserscurl http://localhost:8096/client/api?command=listUsers

<?xml version="1.0" encoding="ISO-8859-1"?><listusersresponse cloud-stack-version="3.0.3.2012-07-04T06:31:57Z"><count>3</count><user><id>7ed6d5da-93b2-4545-a502-23d20b48ef2a</id><username>admin</username><firstname>admin</firstname><lastname>cloud</lastname><created>2012-07-05T12:18:27-0700</created><state>enabled</state><account>admin</account><accounttype>1</accounttype><domainid>8a111e58-e155-4482-93ce-84efff3c7c77</domainid><domain>ROOT</domain><apikey>plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg…

http://www.shapeblue.com/2012/05/10/using-the-api-for-advanced-network-management/

Authenticated calls• Using http(s)• API endpoint for the cloud– http://localhost:8080/client/api?

• Command key to pass the name of the call• Key/value pairs for the arguments• API key of the user making the call• Signature for authorization

API Keys• Generate API keys for the user that will access

the cloud

Creating the signature• Form the request url: list of key=value pairs

joined by & and encoded for http transport• Compute the signature: – lower case values, replace + with %20 – generate the hmac using sha1 hash function– Base64 encode the digest– Encode for http transport

• Form the entire request adding the signature: &signature=

Example>>> request

{'apikey': 'plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg', 'command': 'listUsers', 'response': 'json'}

>>>request_url="&".join(["=".join([r,urllib.quote_plus(request[r])]) for r in request.keys()])

>>>sig_url="&".join(["=".join([r.lower(),urllib.quote_plus(request[r]).lower()]) for r in sorted(request.iterkeys())])

>>>sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_url,hashlib.sha1).digest()).strip())

>>> req=url+request_url+'&signature='+sig

>>> res=urllib2.urlopen(req)

>>> res.read()

REST• REST stands for Representational State

Transfer• Architectural style to design web services

introduced by Roy Fielding (former ASF chair)• Premise:– HTTP protocol is enough to create web services

and change the state of web resources– HTTP methods can be used to change the state– Eases web services design compared to SOAP

http://en.wikipedia.org/wiki/Roy_Fieldinghttp://en.wikipedia.org/wiki/Representational_State_Transfer

REST

• REST style web services couple be implemented with other protocol than http

• But http provides all that is needed

http://en.wikipedia.org/wiki/Representational_State_Transfer

REST API

• The CloudStack API is a query API• It is RESTlike but not RESTfull• Example:listUsers() a GET vs GETupdateUser() a GET vs PATCHcreateUser() a GET vs POSTdeleteUser() a GET vs DELETE

http://gehrcke.de/2009/06/aws-about-api/http://publish.luisrei.com/articles/flaskrest.html

Exercise

• Build a REST interface to CloudStack• Use Flask a Lightweight Python web

framework

http://flask.pocoo.orghttp://publish.luisrei.com/articles/flaskrest.html

Exercisefrom flask import Flask

app = Flask(__name__)

@app.route("/")

def hello():

return "Hello World!"

if __name__ == "__main__":

app.run(debug=True)

Flask allows you to define web routes and functions that get executed when these routes are called.

Exercise@app.route('/login', methods=['GET', 'POST'])

def login():

if request.method == 'POST':

do_the_login()

else:

show_the_login_form()

curl -X DELETE http://localhost:5000/user/b3b60a8dfdf6f-4ce6-a6f9-6194907457a5

{ "deleteuserresponse" : { "success" : "true"} }

https://github.com/runseb/cloudstack-flaskhttp://buildacloud.org/blog/253-to-rest-or-not-to-rest.html

Info• Apache Top Level Project (TLP)• http://cloudstack.apache.org• #cloudstack and #cloudstack-dev on irc.freenode.net• @CloudStack on Twitter• http://www.slideshare.net/cloudstack

• dev-subscribe@cloudstack.apache.org• users-subscribe@cloudstack.apache.org

Welcoming contributions and feedback, Join the fun !