BonFIRE logo and link to main BonFIRE site

Table Of Contents

Previous topic

BonFIRE Architecture

Next topic

Media Type

This Page

BonFIRE API Specification

Overview

An introduction to the API concepts can be found in Overview of Client Tools. Please note that:

  • The API does not support batch operations (i.e. sending one big experiment descriptor with all the resources required). User has to request resources one by one. It is the responsibility of the user to create resources in the right order.
  • Creating a resource at the broker layer means that the resource will be immediately instantiated at the testbed layer. The user is immediately notified of the success or failure of her request.
  • It is the responsibility of the user to start/stop resources based on the needs of her experiment.
  • The API does not provide a monitor resource. The user has to start a compute resource with a predefined image containing the BonFIRE monitoring solution, and properly set up the context in all the other compute resources that need to be monitored.
  • To ensure a limited execution time, a maximum walltime will be enforced for an experiment. When the experiment hits its walltime, the deletion of the experiment will be automatically requested.
  • A new password will be generated for each experiment created. This password will be automatically added to the context of each compute resource, and automatically revoked when the experiment reaches a final state (cancelation/termination).

Interface

Note

The following specification is given for information purposes only. If you are a developer, please note that you should NOT hardcode URIs and HTTP verbs in your client libraries. Use the semantics of the Media Type to derive that kind of information at runtime.

  • The API must have an entry-point.

    GET / HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <root xmlns="http://api.bonfire-project.eu/doc/schemas/occi" href="/">
      <version>0.10.1</version>
      <timestamp>1311582412</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 API must provide the list of active experiments for the currently logged in user. Use query parameters if you want to filter out results.

    GET /experiments?offset={{offset}}&limit={{limit}}&sort_by={{sort_by}}&order={{ASC|DESC}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <collection xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
                href="/experiments?offset=40&limit=20">
      <items offset="40" total="110">
        <experiment>
          ...
        </experiment>
        <experiment>
          ...
        </experiment>
        ...
      </items>
      <link rel="next" href="/experiments?offset=60&limit=20" type="application/vnd.bonfire+xml" />
      <link rel="prev" href="/experiments?offset=20&limit=20" type="application/vnd.bonfire+xml" />
      <link rel="top" href="/experiments?limit=20" type="application/vnd.bonfire+xml" />
      <link rel="parent" href="/" type="application/vnd.bonfire+xml" />
    </collection>
    
  • The API must allow a user to create a new experiment container.

    POST /experiments HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <experiment xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      <name>My Experiment</name>
      <description>Experiment description</description>
      <walltime>7200</walltime>
    </experiment>
    

    =>

    HTTP/1.1 201 Created
    Location: https://api.bonfire-project.eu/experiments/{{experiment_id}}
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <experiment xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
                href="/experiments/{{experiment_id}}">
      <name>My Experiment</name>
      <description>Experiment description</description>
      <walltime>7200</walltime>
      <computes>
        ...
      </computes>
      <storages>
        ...
      </storages>
      <networks>
        ...
      </networks>
      <link rel="parent" href="/" type="application/vnd.bonfire+xml" />
    </experiment>
    
  • The API must allow a user to fetch an experiment she owns:

    GET /experiments/{{experiment_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <experiment xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
                href="/experiments/{{experiment_id}}">
      ...
      <computes>
        <compute href="/locations/{{location_id}}/computes/{{compute_id}}" name="Compute1" />
        <compute href="/locations/{{location_id}}/computes/{{compute_id}}" name="Compute2" />
      </computes>
      <storages>
        <storage href="/locations/{{location_id}}/storages/{{storage_id}}" name="Storage1" />
        <storage href="/locations/{{location_id}}/storages/{{storage_id}}" name="Storage2" />
      </storages>
      <networks>
        <network href="/locations/{{location_id}}/networks/{{network_id}}" name="Network1" />
        <network href="/locations/{{location_id}}/networks/{{network_id}}" name="Network2" />
      </networks>
      <link rel="parent" href="/" type="application/vnd.bonfire+xml" />
    </experiment>
    
  • The API must allow a user to delete an experiment she owns (experiment resources will be deleted in a near future, and the experiment status set to terminated):

    DELETE /experiments/{{experiment_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: */*
    

    =>

    HTTP/1.1 202 Accepted
    Content-Length: 0
    Location: https://api.bonfire-project.eu/experiments/{{experiment_id}}
    
  • The API must allow a user to add a compute resource to an experiment she owns (see the XML Schema Definition for the list of available elements in a compute description):

    POST /experiments/{{experiment_id}}/computes HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <compute xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      <name>Compute name</name>
      <description>Compute description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </compute>
    

    =>

    HTTP/1.1 201 Created
    Content-Type: application/vnd.bonfire+xml
    Location: https://api.bonfire-project.eu/locations/{{location_id}}/computes/{{compute_id}}
    
    <?xml version="1.0" encoding="UTF-8"?>
    <compute  xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
              href="/locations/{{location_id}}/computes/{{compute_id}}">
      <name>Compute name</name>
      <description>Compute description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </compute>
    
  • The API must allow a user to update a compute resource of an experiment she owns:

    PUT /locations/{{location_id}}/computes/{{resource_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Content-Type: application/vnd.bonfire+xml
    Accept: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <compute xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      ...
    </compute>
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <compute  xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
              href="/locations/{{location_id}}/computes/{{compute_id}}">
      ...
    </compute>
    
  • The API must allow a user to add a network resource to an experiment she owns (see XML Schema Definition for the list of available elements):

    POST /experiments/{{experiment_id}}/networks HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <network xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      <name>Network name</name>
      <description>Network description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </network>
    

    =>

    HTTP/1.1 201 Created
    Content-Type: application/vnd.bonfire+xml
    Location: https://api.bonfire-project.eu/locations/{{location_id}}/networks/{{network_id}}
    
    <?xml version="1.0" encoding="UTF-8"?>
    <network  xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
              href="/locations/{{location_id}}/networks/{{network_id}}">
      <name>Network name</name>
      <description>Network description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </network>
    
  • The API must allow a user to add a storage resource to an experiment she owns (see XML Schema Definition for the list of available elements):

    POST /experiments/{{experiment_id}}/storages HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <storage xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      <name>Storage name</name>
      <description>Storage description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </storage>
    

    =>

    HTTP/1.1 201 Created
    Content-Type: application/vnd.bonfire+xml
    Location: https://api.bonfire-project.eu/locations/{{location_id}}/storages/{{storage_id}}
    
    <?xml version="1.0" encoding="UTF-8"?>
    <storage  xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
              href="/locations/{{location_id}}/storages/{{storage_id}}">
      <name>Storage name</name>
      <description>Storage description</description>
      <link rel="location"
            href="/locations/{{location_id}}" />
      ...
    </storage>
    
  • The API must allow a user to delete a resource of an experiment she owns:

    DELETE /locations/{{location_id}}/(computes|networks|storages)/{{resource_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: */*
    

    =>

    HTTP/1.1 202 Accepted
    Content-Length: 0
    Location: https://api.bonfire-project.eu/locations/{{location_id}}/(computes|networks|storages)/{{resource_id}}
    
  • The API must provide the list of participating testbeds:

    GET /locations HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <collection xmlns="http://api.bonfire-project.eu/doc/schemas/occi" href="/locations">
      <items offset="0" total="3">
        <location>
          ...
        </location>
        <location>
          ...
        </location>
        ...
      </items>
      <link rel="parent" href="/" type="application/vnd.bonfire+xml" />
    </collection>
    
  • The API must allow a user to see a location.

    GET /locations/{{location_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    Content-Type: application/vnd.bonfire+xml
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <location xmlns="http://api.bonfire-project.eu/doc/schemas/occi"
              href="/locations/{{location_id}}" >
      ...
      <link rel="computes"
            href="/locations/{{location_id}}/computes"
            type="application/vnd.bonfire+xml" />
      <link rel="networks"
            href="/locations/{{location_id}}/networks"
            type="application/vnd.bonfire+xml" />
      <link rel="storages"
            href="/locations/{{location_id}}/storages"
            type="application/vnd.bonfire+xml" />
      <link rel="parent"
            href="/"
            type="application/vnd.bonfire+xml" />
    </location>
    
  • The API must allow a user to fetch her profile:

    GET /users/{{user_id}} HTTP/1.1
    Host: api.bonfire-project.eu
    Accept: application/vnd.bonfire+xml
    

    =>

    HTTP/1.1 200 OK
    Content-Type: application/vnd.bonfire+xml
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user href="/users/{{user_id}}" xmlns="http://api.bonfire-project.eu/doc/schemas/occi">
      <id>{{user_id}}</id>
      <uid>2019</uid>
      <gid>2000</gid>
      <name>User Name</name>
      <email>user@server.ltd</email>
      <homedir>/home/{{user_id}}</homedir>
      <shell>/bin/sh</shell>
      <keys>ssh-rsa AAAAB3Nz...</keys>
      <link rel="parent" href="/"/>
    </user>
    

XML Schema Definition

The XML Schema Definition formally describes the elements contained in each resource representation.

Status Codes

The previous section shows the status code returned when the request is successful. A user-agent programmed against the BonFIRE API must also support the following status codes and the semantic associated (see Status Code Definitions).

For 2xx and 3xx codes, standard semantics apply. Please refer to the HTTP specification for more information.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

401 Authorization Required

The request requires user authentication. Please retry by adding your credentials to the request.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

404 Not Found

The server has not found anything matching the given Request-URI. You MAY retry the request if you think a resource will be available at some point at this URI.

405 Method Not Allowed

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response will contain an Allow header specifying which methods are allowed.

406 Not Acceptable

You asked for a media type that we do not support. Please change your Accept header.

412 Precondition Failed

The precondition given in one or more of the request-header fields (on conditional PUT/GET/etc.) evaluated to false when it was tested on the server.

415 Unsupported Media Type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

500 Internal Server Error

Something went wrong from our side. You may retry the request. If the error persists, please report to an administrator if you can.

502 Bad Gateway

The server failed at forwarding the request to a subsequent server. Please retry and report to the administrator if the issue persists.

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. Please retry later.

504 Gateway Timeout

The server was unable to fulfill the request in a reasonable amount of time. You may retry the request.

Non Functional Aspects

Cacheability

Every response includes at least validation headers (ETag) and cache control headers (Cache-Control). API clients should use the validation headers to make conditional requests when GETting or PUTting a resource.

Performance

Responses will be returned in less than 60 seconds at most.

Security

The API uses SSL/TLS encryption over HTTP (HTTPS). Only authenticated clients can access the API. The Authentication Scheme that is used is HTTP Basic Authentication.