Accessing the Cloud
This is the first in a series of articles on how to make use of the Mezeo Cloud Storage Platform. This series will help you understand the basics of the Cloud Storage Platform API, highlight interesting features, and the best ways to make use of it. You can find the entire series at the Mezeo Developer Center.
The Mezeo Cloud Storage Platform API provides a single published resource which allows for the discovery of all resources made available by the platform. This published resource is the Cloud resource. When making use of the API, this resource is the place to start.
So, how does one access the Cloud resource?
The Cloud resource is available by issuing a HTTP GET request to the API root of the service. The URL for this resource is specified as /v2 relative to API domain. For example if the API domain were api.example.com, the Cloud resource would be available at http://api.example.com/v2. You should specify the ‘Accept‘ header in the request so that you get the type of representation of the resource you expect. If you do not specify an ‘Accept‘ header, then you will get the default representation of the resource, which may vary per service provider. The type of representation we will be looking at here is the xml variant of the cloud resource, which has a mime-type of ‘application/vnd.csp.cloud+xml‘.
The simplest examples of accessing the Mezeo Cloud Storage Platform API can be shown using cURL. cURL is a handy command line tool for accessing content with URL syntax. The functionality of cURL is also available in libcurl which has bindings in many programming languages. Here is a bare-bones example of accessing the Cloud resource using cURL:
curl -u account_name:password -X GET -H 'Accept: application/vnd.csp.cloud+xml' https://api.example.com/v2
The parameters passed to cURL represent the information required to access the resource. The ‘-u’ option is used to specify the account whose resource we are looking at retrieving. The ‘-X’ is required by curl to tell it to use the GET method on the resource. The ‘-H’ is used to add the accept header for the type of representation we are looking to retrieve. Finally, we specify the URL of the resource we want, in this case the Cloud resource.
A small note on authentication:
The Mezeo Cloud Storage Platform API makes use of HTTP Basic Authentication to provide account credentials. cURL handles creating the appropriate header in the request for you when using the ‘-u’ parameter. Other libraries may require you create the ‘Authentication‘ header yourself.
The result of this action is an XML document that conforms to the XML schema defined for the ‘application/vnd.csp.cloud+xml‘ type. An example of this would look like the following:
<?xml version='1.0' encoding='UTF-8'?>
<cloud xmlns:xlink="http://www.w3.org/1999/xlink">
<rootContainer xlink:href="https://api.example.com/v2/containers/6F4D9C8C-3E56-11DE-981E-2B62DFFCC881" xlink:type="simple"/>
<contacts xlink:href="https://api.example.com/v2/contacts" xlink:type="simple"/>
<shares xlink:href="https://api.example.com/v2/shares" xlink:type="simple"/>
<projects xlink:href="https://api.example.com/v2/projects" xlink:type="simple"/>
<metacontainers xlink:href="https://api.example.com/v2/metacontainers" xlink:type="simple"/>
<account xlink:href="https://api.example.com/v2/account" xlink:type="simple"/>
<tags xlink:href="https://api.example.com/v2/tags" xlink:type="simple"/>
<recyclebin xlink:href="https://api.example.com/v2/recyclebin" xlink:type="simple"/>
</cloud>
The Cloud representation works as a gateway to the other resources available, with the accounts storage beginning with the rootContainer element.
Language Examples
This same request can be made using any programming language. The Mezeo Cloud Storage Platform API is designed to be language neutral. Here are some examples of performing the same action with a couple of specific languages:
Python
Recent versions of python include the urllib2 package which provides an easy way to make HTTP requests. The only tricky part here is providing the proper authentication information. You can use urllib2′s password manager to handle the authentication for you or you can create the ‘Authentication‘ header yourself.
To use urllib2′s password manager, you will need to inform urllib2 about the account and password information and install an ‘opener’. An example of this would look like this:
import urllib2
passmgr = utllib2.HTTPPasswordMgrWithDefaultRealm()
passmgr.add_password(None, "https://api.example.com/v2/", "account_name", "password")
authhandler = urllib2.HTTPBasicAuthHandler(passmgr)
opener = urllib2.build_opener(authhandler)
urllib2.install_opener(opener)
The alternative method to this is to specify the ‘Authentication‘ header in the request. Here is an example of how to request the actual resource, continuing from the example above:
hdr = {'Accept':'application/vnd.csp.cloud+xml'}
request = urllib2.Request('https://api.example.com/v2/', headers=hdr)
handle = None
try:
handle = urllib2.urlopen(request)
except urllib2.URLError, ex:
print ("Failed request: " % repr(ex))
raise ex
print ("Representation:\n%s" % handle.read())
handle.close()
Java
Using HttpClient makes it easy to access the Mezeo Cloud Storage Platform API using Java.
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.*;
import org.apache.commons.httpclient.params.HttpMethodParams;
import java.io.*;
public class AccessTheCloud {
public static void main(String[] args) {
String url = "https://api.example.com/v2/";
InputStream stream = null;
URI uri = new URI(url);
UsernamePasswordCredentials credentials = new UsernamePasswordCredentials("account_name", "password");
HttpContext localContext = new BasicHttpContext();
DefaultHttpClient httpclient = new DefaultHttpClient();
HttpGet httpget = new HttpGet(uri);
httpget.addHeader("Accept","application/vnd.csp.cloud+xml");
httpclient.getParams().setAuthenticationPreemptive(true);
httpclient.getState().setCredentials(new AuthScope("api.example.com", 443, AuthScope.ANY_REALM), credentials);
try {
HttpResponse response = httpclient.execute(httpget,localContext);
int status = response.getStatusLine().getStatusCode();
if (status >= 300) {
System.err.println("Request failed: " + httpget.getStatusLine());
} else {
HttpEntity entity = response.getEntity();
if (entity != null) {
stream = entity.getContent();
BufferedReader in = new BufferedReader (new InputStreamReader (stream));
String line;
while ((line = in.readLine()) != null) {
System.out.println (line);
}
}
}
}
catch(IOException ioe) {
System.err.println("Caught exception: " + ioe.getMessage());
}
}
}
.Net (C#)
We can accomplish the same thing with C# as follows in this example:
string account = "account_name"
string password = "password"
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("https://api.example.com/v2/");
webRequest.Credentials = new NetworkCredential(account, password);
webRequest.preAuthenticate = true;
webRequest.Method = "GET";
HttpWebResponse response = (HttpWebResponse)webRequest.GetResponse();
StringBuilder responseString = new StringBuilder();
using (Stream responseStream = response.GetResponseStream())
{
byte[] buffer = new byte[1024];
int bytes_read = 0;
while ((bytes_read = responseStream.Read(buffer, 0, buffer.Length)) > 0)
{
responseString.Append(Encoding.UTF8.GetString(buffer, 0, bytes_read));
}
}
What to do with the Cloud once you have it?
Once we have obtained a representation of the Cloud resource, we have to keys to access all of the other exposed resources. The elements specified in the XML representation of the Cloud resource each specify another resource exposed by the platform. Obtaining the Cloud is the first step in interacting with the Mezeo Cloud Storage Platform.