Intro to CloudStack API


Published on

A walk through of the CloudStack API. full screencast available at

An API to your cloud orchestrator is key to automation of your data center.

We go through the basics of Query API calls, unauthenticated on the integration port and authenticated calls using the access and secret keys of a users and computing a signature. We show how to compute a signature in Python.

We also highlight various CloudStack clients in many different languageas (java, php, ruby, clojure etc..) and show how to explore the API using firebug console in firefox or via the CloudStack interfactive shell cloudmonkey. This is a good complement to my talk on CloudMonkey.

Published in: Technology

Intro to CloudStack API

  1. 1. Introduction to the CloudStackAPISebastien Goasguen@sebgoa
  2. 2. Outline• Documentation• Clients• Exploration• Integration port• Signing requests• REST or not REST
  3. 3. Documentation
  4. 4. Clients• 15 clients andcounting… on Github• Java, Python, Perl,Ruby, C#, php, Clojure
  5. 5. Exploration• Use a debugger console• E.g Firebug• As you navigate the UI,check the http calls thatare being made• Identify the methods• Identify the parameterspassed to each call
  6. 6. HTTPbased• API calls made via HTTP(s)• Pass name of the call as command• Pass list of key/value pairs as arguments tothe call• GET method• Response can be XML or JSON• Query API that is RESTlike
  7. 7. 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
  8. 8. Using theintegration porthttp://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=""><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…
  9. 9. 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
  10. 10. API Keys• Generate API keys for the user that will accessthe cloud
  11. 11. Creating the signature• Form the request url: list of key=valuepairs joined by & and encoded for httptransport• 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=
  12. 12. 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(,sig_url,hashlib.sha1).digest()).strip())>>> req=url+request_url+&signature=+sig>>> res=urllib2.urlopen(req)>>>
  13. 13. REST• REST stands for Representational StateTransfer• Architectural style to design web servicesintroduced by Roy Fielding (former ASF chair)• Premise:– HTTP protocol is enough to create web servicesand change the state of web resources– HTTP methods can be used to change the state– Eases web services design compared to SOAP
  14. 14. REST• REST style web services couple beimplemented with other protocol than http• But http provides all that is needed
  15. 15. 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
  16. 16. Exercise• Build a REST interface to CloudStack• Use Flask a Lightweight Python webframeworkhttp://flask.pocoo.org
  17. 17. Exercisefrom flask import Flaskapp = Flask(__name__)@app.route("/")def hello():return "Hello World!"if __name__ == "__main__" allows you to define web routes andfunctions that get executed when these routesare called.
  18. 18. Exercise@app.route(/login, methods=[GET, POST])def login():if request.method == POST:do_the_login()else:show_the_login_form()curl -X DELETEhttp://localhost:5000/user/b3b60a8dfdf6f-4ce6-a6f9-6194907457a5{ "deleteuserresponse" : { "success" : "true"} }
  19. 19. Info• Apache Top Level Project (TLP)•• #cloudstack and #cloudstack-dev on• @CloudStack on Twitter••• users-subscribe@cloudstack.apache.orgWelcoming contributions and feedback, Join the fun !