API

Introduction

At the time of writing, Grid5000 is mainly accessed and operated via shell commands executed from frontend machines. To ease scripting and provide better access to the grid functionalities, an API is currently developed by the Grid5000 Technical Committee. This API consists in a layer on top of most of the Grid5000 tools that will provide stable and well-defined interfaces accessible via the HTTP protocol.

Most of the standardization effort is achieved by trying to be as close as possible to the principles of a REST (REpresentational State Transfer) architecture, which recommends to define the semantics of an operation on a resource by means of the standard HTTP operations (e.g. GET, PUT, POST, DELETE) and the standard HTTP status codes (e.g. 200, 401, 404, 500).

The concept of a REST resource must not be confused with the concept of a resource in the context of Grid5000: a REST resource, identified by a URI (e.g. /sites/rennes), represents a specific view into an object, which MAY incidentally be a Grid5000 resource (e.g. node, switch) but not necessarily.

As a consequence of using the HTTP protocol as an application protocol, any HTTP client can be used to query the API: command-line tools (cURL), browsers and the numerous HTTP libraries available in the vast majority of programming languages.

Access to the API

The API entry-point is:

 https://api.grid5000.fr

However, during the first phase of the deployment of the Grid5000 API, the access is restricted to requests coming from one of the Grid5000 ACCESS machines. Thus, if you are connected on a machine that is not and ACCESS machine, you must create an SSH tunnel between your machine and an ACCESS machine of your choice.

 $ ssh -NL 3443:api.grid5000.fr:443 login@access.site.grid5000.fr

If you want to always get the nearest (geographically speaking) ACCESS machine, you may choose to enter:

 $ ssh -NL 3443:api.grid5000.fr:443 login@access.grid5000.fr

As a consequence, the API entry-point, as seen from your local machine, will be:

 https://localhost:3443

Versioning

The Grid5000 API is made up of multiple APIs that may evolve independently from each other. Changes occurring in one API are reflected by a new version number for this particular API. In the long term, scripts or applications that are built upon multiple APIs may have to deal with multiple version numbers for each API, which is not a very enjoyable perspective. That's why the Grid5000 API is globally versioned: a global version id will map to the specific API version numbers in a transparent manner. All you have to do is to suffix the API entry-point with the global version id of your choice:

 https://api.grid5000.fr/global-version-id

Or, if you connect via an SSH tunnel:

 https://localhost:3443/global-version-id

The format of the global version id is as follows:

 major.minor-quality

e.g.

 1.0-stable

Scripts and applications that are programmed against a specific global version id should never encounter problems due to changes in the APIs, until the official deprecation of the version.

The list of the past and current versions supported by the Grid5000 API is available at: #Global_Version_IDs.

Resources

The resources that can be queried are described in the documentation of each API. The resources are identified by a URI, which should be added to the end of the API entry-point to form the URL. For example, /sites/rennes/versions/current is a resource exposed by the Reference API. If you would like to get the representation of this resource as it is returned by the 1.0-stable version of the Grid5000 API, the URL to enter in your HTTP client would be:

 https://api.grid5000.fr/1.0-stable/sites/rennes/versions/current

Or, if you connect via an SSH tunnel:

 https://localhost:3443/1.0-stable/sites/rennes/versions/current

The list of the APIs and their documentation is available at: #APIs.

Format

When you query a REST resource, you ask for a representation of an object. Depending on the resource you are requesting, there could be multiple representations available. It is the responsibility of the user to indicate which representation (or format) it accepts.

To set the format that you accept, you could either explicitly insert the format at the end of the URL, e.g.:

 GET entry-point/global-version-id/resource.json

Or, you may prefer to set the Accept HTTP header to the correct mime type, e.g.:

 GET entry-point/global-version-id/resource
 Accept: application/json

If you put both, the Accept HTTP header will be ignored.

APIs

Reference API

• Documentation

Monitoring API

• Documentation