BonFIRE logo and link to main BonFIRE site

Previous topic

Exporting Monitoring Data to CSV

Next topic

First Steps Using the API

This Page

Introduction to the BonFIRE APIΒΆ

One can interact with BonFIRE in many ways. First there is the portal, and then there is the API, which is exposed over the HTTP protocol.

Using the BonFIRE API requires that you are already registered as a BonFIRE user. If not, head over to Getting a BonFIRE Account and follow the instructions.

The API is designed for users, who want to programmatically access the BonFIRE capabilities. It allows you to script your experiments, easily (re)run them, and makes you more productive.

You may be familiar with APIs exposed over HTTP. For example, Amazon and all the other popular cloud providers offer HTTP APIs. You may also be familiar with the REST acronym, which designates an architectural style for building distributed applications.

BonFIRE offers an HTTP API that tries to closely follow the REST principles, among which are:

  • Uniform Interface:

    Our API supports the standardized HTTP verbs (GET, POST, PUT, DELETE, etc.) to interact with an API resource, and one of the standardized HTTP status codes (200 OK, 201 Created, 404 Not Found, etc.) will be returned with every response to express the semantics of the result. Each of these verbs and status has a well-defined semantic associated, and we invite you to have a look at the relevant parts of the HTTP specification (RFC2616) if you’re not familiar with them (see Method Definitions and Status Code Definitions).

  • Self-descriptive Messages:

    An HTTP message is made of two sections: the HTTP header, and the (optional) HTTP body. The header contains meta-data about the messages. For instance in the case of an HTTP request, it contains the HTTP verb, the URL, the target Host, and other fields that better characterize the message being sent, and expectations over the response. In the case of an HTTP response, the header will contain the status code, the type of the content being returned, caching details, etc. The body will contain the content being transferred between the client and the server.

    An example HTTP request could be:

    GET / HTTP/1.1
    Host: api.bonfire-project.eu:444
    Accept: */*
    Authorization: Basic XXX
    Accept-Encoding: gzip, deflate

    And the corresponding response:

    HTTP/1.1 200 OK
    Vary: Authorization,Accept
    Transfer-Encoding: chunked
    Etag: "fa2ba873343ba638123b7671c8c09998"
    Content-Type: application/vnd.bonfire+xml; charset=utf-8
    Date: Wed, 01 Jun 2011 14:59:30 GMT
    Server: thin 1.2.11 codename Bat-Shit Crazy
    Allow: GET,OPTIONS,HEAD
    Cache-Control: public,max-age=120
    Connection: close
    
    <?xml version="1.0" encoding="UTF-8"?>
    <root xmlns="http://api.bonfire-project.eu/doc/schemas/occi" href="/">
      <version>0.8.9</version>
      <timestamp>1306940370</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 complete list of standardized HTTP header fields and their semantics can be found in the Header Field Definitions section of RFC2616.

  • Hypermedia as the Engine of Application State:

    When you look at the documentation of most of the “RESTful APIs” present on the net, you’ll be given a page full of URIs, methods that can be used on them, status codes that can be returned, etc. However, in the same way that “classic” web sites don’t have to provide you with the full list of page URLs before you can start navigating through the site, as a client of our API you don’t have to know before hand all the URIs that you can access.

    If you think about it, on “classic” web sites, you just hit some entry-point URL and you get back a page written in HTML that contains a set of hyperlinks to other resources. Then, based on the semantic that is given to each link (most of the time through textual description), you click on the link that interests you the most to pursue your navigation towards your goal (if any).

    The BonFIRE API follows the same rule: every response comes with a set of link relationships that points to related resources, which allows a client to navigate through the API without knowing the exact URIs before-hand. The semantic of each link is described using a relationship characterizer (the rel attribute). In the example above, you see that our root resource (located at /, the only URI you need to know), has three related resources: experiments, locations, users. You can probably infer the meaning of each of them, but in doubt check the BonFIRE Media Type specification (application/vnd.bonfire+xml) to learn everything you need to know about it.