blob: d25536430318a9b8265c8ecad9dea237214863f9 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Usage</title>
<!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- Le JavaScript -->
<script src="/assets/js/jquery-1.7.1.min.js" type="text/javascript"></script>
<script src="/assets/js/bootstrap-dropdown.js" type="text/javascript"></script>
<script src="/assets/js/jquery.tweet.js" type="text/javascript"></script>
<script src="/assets/js/application.js" type="text/javascript"></script>
<script src="/assets/js/bootstrap-transition.js"></script>
<script src="/assets/js/bootstrap-alert.js"></script>
<script src="/assets/js/bootstrap-modal.js"></script>
<script src="/assets/js/bootstrap-scrollspy.js"></script>
<script src="/assets/js/bootstrap-tab.js"></script>
<script src="/assets/js/bootstrap-tooltip.js"></script>
<script src="/assets/js/bootstrap-popover.js"></script>
<script src="/assets/js/bootstrap-button.js"></script>
<script src="/assets/js/bootstrap-collapse.js"></script>
<script src="/assets/js/bootstrap-carousel.js"></script>
<script src="/assets/js/bootstrap-typeahead.js"></script>
<!-- Le styles -->
<link href="/assets/css/bootstrap.css" rel="stylesheet">
<link href="/assets/css/application.css" rel="stylesheet">
<link rel="shortcut icon" href="/assets/img/favicon.ico">
</head>
<body><div style="background: red"><h1>2015/07/20 - Apache Deltacloud has been retired. </h1><h2>For more information, please explore the <a href="http://attic.apache.org/">Attic</a>. </h2></div>
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="brand" href="/"><img src="/assets/img/logo.png" width="152"
alt="Deltacloud API"/></a>
<ul class="nav top-nav">
<li><a href="/">Home</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">About<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/about.html">What is Deltacloud?</a></li>
<li><a href="/drivers.html#drivers">Supported Providers</a></li>
</ul>
</li>
<li><a href="/download.html">Download</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Installation<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/install-deltacloud.html">Install Deltacloud</a></li>
<li><a href="/run-deltacloud-server.html">Run the Deltacloud Server</a></li>
</ul>
</li>
<li class="dropdown">
<a href="/usage.html" class="dropdown-toggle" data-toggle="dropdown">Usage<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/usage.html#usingapi">Using API</a></li>
<li><a href="/usage.html#clients">Client Libraries</a></li>
<li><a href="/command-tools.html">Command Line Tools</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/getting-sources.html">Getting Sources</a></li>
<li><a href="/how-to-contribute.html">How Can I Contribute?</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/rest-api.html">Deltacloud REST API</a></li>
<li><a href="/curl-examples.html">Deltacloud API cURL examples</a></li>
<li><a href="/drivers.html">Drivers API</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">CIMI<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/cimi-rest.html">CIMI REST API</a></li>
<li><a href="/cimi-curl.html">CIMI cURL Examples</a></li>
</ul>
</li>
<li><a href="/contact.html">Contact</a></li>
</ul>
</div>
</div>
</div>
<div class="container content">
<p><br></p>
<h3 id="usingapi">Using API</h3>
<h3 id="clients">Clients</h3>
<p>Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.</p>
<h3>The Deltacloud Ruby Client</h3>
<p>You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:</p>
<pre>$ sudo gem install deltacloud-client</pre>
<p>The Deltacloud client consists of a Ruby library (packaged as a Ruby gem) which you can use to interact with the Deltacloud server and control your cloud infrastructure across cloud providers. </p><p>
</p><p>To use the client, you must require <strong>deltacloud</strong>:</p>
<pre>require 'deltacloud'</pre>
<p>Connect to a Deltacloud provider:</p>
<pre>
require 'deltacloud'
api_url = 'http://localhost:3001/api'
api_name = 'mockuser'
api_password = 'mockpassword'
client = DeltaCloud.new( api_name, api_password, api_url )
# work with client here
</pre>
<p>In addition to creating a client, you can specify operations within a block included on the initialization.</p>
<pre>
DeltaCloud.new( api_name, api_password, api_url ) do |client|
# work with client here
end
</pre>
<p>In case of a failure, any underlying HTTP transport exceptions will be thrown away and returned back to the caller.</p>
<p>
To work with another driver, just switch the client:
</p>
<pre>
client = DeltaCloud.new( api_name, api_password, api_url )
# switch the client to use EC2 driver
ec2 = client.with_config(:driver =&gt; :ec2)
# switch the client to use OpenStack driver
openstack = client.with_config(:driver =&gt; :openstack)
</pre>
<a class="btn btn-inverse btn-large" style="float: right" href="ruby-client.html">Work with the Ruby client</a>
<br>
<br>
<h3>HTTP clients - cURL</h3>
<p>
Basically, you interact with the Deltacloud server via HTTP calls, so you can use any HTTP client to talk to Deltacloud using the <a href="rest-api.html">Deltacloud REST API</a>.
</p>
<p>
<a href="http://curl.haxx.se/">cURL</a> is a popular command line tool available on most modern linux distributions. See the following examples to learn how to use cURL to interact with Deltacloud. There is an assumption that the Deltacloud server is running on locahost:3001 and was started with the 'ec2' driver (i.e., deltacloudd -i ec2 ).
</p>
<p>
Get a list of all <strong>images</strong> available in the back-end cloud:
</p>
<pre>
curl --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/images?format=xml"
</pre>
<p>
The cURL <strong>--user</strong> option is used to specify the <strong>username:password</strong> credentials for access to the back-end cloud provider (Amazon EC2 in this case).</p>
<p>Create a new <strong>instance</strong> from the image with id 'ami-f51aff9c', in realm 'us-east-1c', with the hardware profile 'c1.medium', in firewall 'default':
</p>
<pre>
curl -X POST -F "keyname=eftah" -F "image_id=ami-f51aff9c"
-F "realm_id=us-east-1c" -F "hwp_id=c1.medium" -F "firewalls1=default"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/instances?format=xml"
</pre>
<p>Delete a <strong>firewall</strong> called 'develgroup':</p>
<pre>
curl -X DELETE
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/firewalls/develgroup?format=xml
</pre>
<p>
Create a <strong>blob</strong> called 'my_new_blob' within the bucket 'mybucket' from a local file with <strong>HTTP PUT</strong> specifying its content type and setting some metadata <strong>key:value</strong> pairs:
</p>
<pre>
curl -H 'content-type: text/html' -H 'X-Deltacloud-Blobmeta-Name:mariosblob'
-H 'X-Deltacloud-Blobmeta-Version:2.1' --upload-file
"/home/marios/Desktop/somefile.html"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
</pre>
<p>
Retrieve <strong>blob metadata</strong> for the blob called 'my_new_blob':
</p>
<pre>
curl -iv -X HEAD
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
</pre>
<p>
The <strong>'-iv'</strong> flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body).
</p>
<a class="btn btn-inverse btn-large" style="float: right" href="curl-examples.html">Working with cURL</a>
<br>
<br>
<h3>Libdeltacloud Client (C library)</h3>
<p>
Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API.
</p>
Get the source code:
<pre>
$ git clone git://git.fedorahosted.org/deltacloud/libdeltacloud.git
</pre>
<p>
As of version 0.9, libdeltacloud is mostly <strong>API stable</strong>, but not ABI stable. The difference between the two is subtle but important. A library that is ABI (Application Binary Interface) stable means, that programs using the library don't need to be modified nor re-compiled when a new version of the library comes out. A library that is API (Application Programming Interface) stable means that programs using the library don't need to be modified, but may need to be re-compiled when a new version of the library comes out. The reason is that the sizes of structures in the library might change, which can lead to a misunderstanding between what the library and the program thinks the size of a structure is.
</p>
<p>
Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
</p>
<a class="btn btn-inverse btn-large" style="float: right" href="http://deltacloud.apache.org/libdeltacloud/index.html">Libdeltacloud documentation</a>
<br>
<footer class="footer">
<p class="pull-right"><span class='icon-circle-arrow-up'>&nbsp;</span><a href="#">Back to top</a></p>
<div class='row'>
<div class='span3'>
<img src="/assets/img/asf.png" alt="Apache Software Foundation"/>
</div>
<div class='span9'>
<strong>Apache Deltacloud</strong> is a top-level project at the <a
href="http://www.apache.org">Apache Software Foundation</a>,
having graduated from the ASF Incubator in October
2011. Through a collaborative and meritocratic development process, Apache
projects deliver enterprise-grade, freely available software products that
attract large communities of users.
</div>
</div>
</footer>
</div> <!-- /container -->
<!-- Piwik -->
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://stats.salasaga.org/aeolus/piwik/" : "http://stats.salasaga.org/aeolus/piwik/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
try {
var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 2);
piwikTracker.trackPageView();
piwikTracker.enableLinkTracking();
} catch( err ) {}
</script><noscript><p><img src="http://stats.salasaga.org/aeolus/piwik/piwik.php?idsite=2" style="border:0" alt="" /></p></noscript>
<!-- End Piwik Tracking Code -->
</body>
</html>