BonFIRE logo and link to main BonFIRE site

Table Of Contents

Previous topic

BonFIRE Portal

Next topic

Command Line Interface Tools

This Page

OCCI/API via HTTP(cURL)

cURL is a command line tool for transferring data with URL syntax, supporting FTP, [..] HTTP, HTTPS, [..] and TFTP. cURL supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, kerberos...), file transfer resume, proxy tunneling and a busload of other useful tricks.

Installing cURL

MacOS

cURL is installed by default on the MacOS X OS. Nothing to do for you!

Linux

Use your package manager to install cURL.

Either (debian-based distributions):

$ sudo apt-get install curl

or (redhat-based distributions):

$ sudo yum install curl

Windows

Download and install the cURL package from the website at http://curl.haxx.se/download.html.

Your First Requests

The BonFIRE API entry-point is located at https://api.bonfire-project.eu/. Open your Terminal program (or the cURL executable if you’re on Windows), and use cURL to fetch the resource located at that URL:

$ curl -k -i https://api.bonfire-project.eu/

Note

The -k flag is necessary to disable the SSL certificate verification (we don’t use - yet - a trusted SSL certificate).

Hit ENTER to execute the cURL command, and here is what you should see in response:

HTTP/1.1 401 Authorization Required
Date: Fri, 08 Jul 2011 08:12:25 GMT
WWW-Authenticate: Basic realm="BonFIRE API"
Content-Length: 489
Connection: close
Content-Type: text/html; charset=iso-8859-1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>401 Authorization Required</title>
</head><body>
<h1>Authorization Required</h1>
<p>This server could not verify that you
are authorized to access the document
requested.  Either you supplied the wrong
credentials (e.g., bad password), or your
browser doesn't understand how to supply
the credentials required.</p>
<hr>
<address>Apache/2.2.3 (CentOS) Server at api.bonfire-project.eu Port 444</address>
</body></html>

What you see is the HTTP response you received from the server. The first section contains the HTTP headers, and the last section contains the payload (here: text/html type). The first line indicates the status of the response, which is 401 Authorization Required. It means that the server requires you to authenticate using your BonFIRE credentials to continue.

Note

The -i flag displays the HTTP response headers. If you omit that flag, you will only see the response payload.

Authentication

The BonFIRE API is using the standard HTTP Basic Authentication mechanism to perform access restriction. You can tell cURL under which user you want to authenticate using the -u flag (replace BONFIRE_USER by your BonFIRE username):

$ curl -k -i https://api.bonfire-project.eu/ -u BONFIRE_USER

cURL will prompt you for your password, and if successful will return the following response:

HTTP/1.1 200 OK
Date: Fri, 08 Jul 2011 08:17:55 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
Allow: GET,OPTIONS,HEAD
Cache-Control: public,max-age=120
Content-Type: application/vnd.bonfire+xml; charset=utf-8
ETag: "4bb22c9cdd9803c44575f93db76e235c"
X-UA-Compatible: IE=Edge,chrome=1
X-Runtime: 0.007996
Vary: Authorization,Accept
Connection: close
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="http://api.bonfire-project.eu/doc/schemas/occi" href="/">
  <version>0.11.6</version>
  <timestamp>1310113075</timestamp>
  <link rel="experiments" href="/experiments" type="application/vnd.bonfire+xml"/>
  <link rel="locations" href="/locations" type="application/vnd.bonfire+xml"/>
  <link rel="users" href="/users" type="application/vnd.bonfire+xml"/>
</root>

The HTTP status of 200 OK indicates that the server was able to process your request and that everything went fine. You can see that the response is now of type application/vnd.bonfire+xml (the Media Type), and that the response payload contains a number of link elements.

Let’s fetch the /experiments resource:

$ curl -k -i https://api.bonfire-project.eu/experiments -u BONFIRE_USER

Here’s what you should see:

HTTP/1.1 200 OK
Date: Fri, 08 Jul 2011 08:21:31 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
Cache-Control: public,max-age=30
Allow: GET,POST,OPTIONS,HEAD
Content-Type: application/vnd.bonfire+xml; charset=utf-8
ETag: "f9c146a48119b95d2adbae6aed479a1a"
X-UA-Compatible: IE=Edge,chrome=1
X-Runtime: 0.011916
Vary: Authorization,Accept
Connection: close
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<collection xmlns="http://api.bonfire-project.eu/doc/schemas/occi" href="/experiments">
  <items offset="0" total="0">
  </items>
  <link href="/" rel="parent" type="application/vnd.bonfire+xml"/>
</collection>

This is the list of your active experiments. Most probably that list is empty.

Note

If you want to avoid entering your password each time you make a request, cURL can automatically find and send the credentials for a specific website by looking at a special file named ~/.netrc (on Linux/MacOS systems). Here is how you would create such a file:

$ cat <<EOF >> ~/.netrc
machine api.bonfire-project.eu
login your-bonfire-login
password your-bonfire-password
EOF
chmod 600 ~/.netrc

Then, you just have to add the -n flag to the cURL command to tell it to use the ~/.netrc file to find your credentials for the BonFIRE API:

$ curl -kni https://api.bonfire-project.eu/experiments

An interesting point to note in the previous response is that it includes an Allow HTTP header, which lists the HTTP verbs (see Overview of Client Tools for more information) that you can use on the current resource.

For example, the GET method is authorized (that’s what we just did, since the cURL tool issues GET requests by default). But you can also see that this resource allows POST requests to be made.

Creating New Resources

Since POST has a semantic of CREATE, it means that you can CREATE a new experiment by POSTing on the /experiments URI. Using the Media Type description to look up how to represent an experiment in BonFIRE+XML, you could come up with the following request to create an experiment:

$ curl -k -i https://api.bonfire-project.eu/experiments -u BONFIRE_USER \
  -H 'Content-Type: application/vnd.bonfire+xml' -X POST -d \
  '<?xml version="1.0" encoding="UTF-8"?>
  <experiment xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
    <name>My First Experiment using cURL</name>
    <description>Experiment description</description>
    <walltime>3600</walltime>
  </experiment>'

Hit ENTER, enter your password when prompted for, and you should get back a response like the following:

 HTTP/1.1 201 Created
 Date: Fri, 08 Jul 2011 09:29:32 GMT
 Server: thin 1.2.11 codename Bat-Shit Crazy
Location: https://api.bonfire-project.eu/experiments/1155
 Content-Type: application/vnd.bonfire+xml; charset=utf-8
 Cache-Control: no-cache
 X-UA-Compatible: IE=Edge,chrome=1
 X-Runtime: 0.112345
 Vary: Authorization,Accept
 Connection: close
 Transfer-Encoding: chunked

 <?xml version="1.0" encoding="UTF-8"?>
 <experiment href="/experiments/1155" xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
   <id>1155</id>
   <description>Experiment description</description>
   <name>My First Experiment using cURL</name>
   <walltime>3600</walltime>
   <user_id>crohr</user_id>
   <status>ready</status>
   <networks>
   </networks>
   <computes>
   </computes>
   <storages>
   </storages>
   <link rel="parent" href="/"/>
   <link rel="storages" href="/experiments/1155/storages"/>
   <link rel="networks" href="/experiments/1155/networks"/>
   <link rel="computes" href="/experiments/1155/computes"/>
 </experiment>

As indicated by the HTTP status 201 Created, your experiment has been successfully created. You can find the URI of the newly created experiment in the Location HTTP header (https://api.bonfire-project.eu/experiments/1155). The response payload contains the experiment description, with links to other resources.

Deleting Resources

If you fetch the newly created experiment resource, you’ll see that the Allow header is different (replace the URI with the one you obtained in the previous response):

$ curl -kni https://api.bonfire-project.eu/experiments/1155
HTTP/1.1 200 OK
Date: Fri, 08 Jul 2011 09:49:31 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
Cache-Control: public,max-age=30
Allow: GET,PUT,DELETE,OPTIONS,HEAD
Content-Type: application/vnd.bonfire+xml; charset=utf-8
ETag: "50ea93fb5babdbe0a3b98382b11e757f"
X-UA-Compatible: IE=Edge,chrome=1
X-Runtime: 0.018795
Vary: Authorization,Accept
Connection: close
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<experiment href="/experiments/1155" xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
  <id>1155</id>
  <description>Experiment description</description>
  <name>My First Experiment using cURL</name>
  <walltime>3600</walltime>
  <user_id>crohr</user_id>
  <status>ready</status>
  <networks>
  </networks>
  <computes>
  </computes>
  <storages>
  </storages>
  <link rel="parent" href="/"/>
  <link rel="storages" href="/experiments/1155/storages"/>
  <link rel="networks" href="/experiments/1155/networks"/>
  <link rel="computes" href="/experiments/1155/computes"/>
</experiment>

For an Experiment resource, you can see that PUT and DELETE requests are now supported, while POST is not allowed. PUT has the semantic of UPDATE, while DELETE has the semantic of, well, DELETE. Therefore you know you can DELETE the experiment by issuing the following request:

$ curl -kni https://api.bonfire-project.eu/experiments/1155 -X DELETE
HTTP/1.1 202 Accepted
Date: Fri, 08 Jul 2011 09:51:48 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
 Location: https://api.bonfire-project.eu/experiments/1155
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache
X-UA-Compatible: IE=Edge,chrome=1
X-Runtime: 0.026081
Vary: Authorization,Accept
Connection: close
Transfer-Encoding: chunked

Here you see another status code: 202 Accepted, which means your request for deletion has been accepted, and will be shortly processed.

Bonus Points

At this point, you should probably take some time to explore the other resources that were advertised at https://api.bonfire-project.eu/ (e.g. locations, users, etc.). Also, you could add the -v flag (verbose) to see what’s being sent over the wire when you’re doing a GET or POST request. Then, if you want to see a complete example of the HTTP requests required to create a whole experiment with compute, network, and storage resources, you should have a look at Example HTTP Request/Response Session.