API

Current State

An early prototype of the upcoming API is available at: https://helpdesk.grid5000.fr/api/rennes. Not stable, only a subset of sites are included (grenoble, bordeaux, rennes, sophia).

Enhancements are planned on a regular basis. Backwards-compatibility is not assured. Servers might be down at any time. Please refer to this page to get the main entry-point of the API as it may change.

The API is totally distributed. That is, the data is pulled from local datasets (OAR2) without the need for a centralized database.

Available Resources

API entry-point: https://helpdesk.grid5000.fr/api/rennes

The availability of an HTML format means that you can use your browser as a native API client (e.g. click on https://helpdesk.grid5000.fr/api/rennes/sites).

GET /sites [html | json | xmlrpc]

list of sites (cached for 1 hour). JSON response has the following format:

 {
   "items": [], # array of site hashes ({"uid": "...", "location": "...", "uri": "...", ...})
   "errors": [], # array of error messages
   "generated_at": 123456789 # number of seconds since epoch (UTC time)
 }

GET /sites/{site_uid} [html | json | xmlrpc]

site's details

GET /sites/{site_uid}/hosts [html | json | xmlrpc]

list of site's hosts (cached for 90 seconds). JSON response has the following format:

 {
   "items": [], # array of host hashes ({"uid": "...", "cluster_uid": "...", "site_uid": "...", ...})
   "errors": [], # array of error messages
   "generated_at": 123456789 # number of seconds since epoch (UTC time)
 }

GET /sites/{site_uid}/hosts/{host_uid} [html | json | xmlrpc]

host's details

GET /sites/{site_uid}/clusters [html | json | xmlrpc]

list of site's clusters (cached for 1 hour)

Getting Started

Ruby client

Put this code in a g5k-client.rb file. It will output the current list of sites and, for each one, the list of its clusters and dead nodes:

 require 'rubygems'
 require 'rest_client' # sudo gem install rest-client
 require 'json' # sudo gem install json
 
 api = RestClient::Resource.new('https://helpdesk.grid5000.fr/api/rennes', 'G5Klogin', 'G5Kpassword')
 begin
   # get the list of sites
   sites_response = JSON.parse api['/sites'].get(:accept => 'application/json') # or api['/sites.json'].get
   sites_response['items'].each do |site|
     puts "------------------ #{site['uid']} ------------------"
     puts "Clusters = [#{site['clusters'].map{|cluster| cluster['uid']}.join(", ")}]"
 
     # get the site's hosts. we use the URI contained in the response to locate and get new information.
     hosts_response = JSON.parse api["#{site['uri']}/hosts"].get(:accept => 'application/json')
     puts "Dead hosts = [#{hosts_response['items'].select{|host| host['state'] == 'dead'}.collect{|host| host['uid']}.join(", ")}]"
   end
   
   # display errors if any
   sites_response['errors'].each do |error|
     puts error
   end
 rescue RestClient::ResourceNotFound
   puts 'Resource not found.'
 rescue RestClient::RequestTimeout
   puts 'Timeout.'
 rescue RestClient::Unauthorized
   puts 'Unauthorized.'
 rescue RestClient::RequestFailed
   puts 'Request failed.'
 rescue RestClient::ServerBrokeConnection 
   puts 'Connection broken.' 
 rescue Exception => e
   puts e.message
 end

Run with:

 ruby g5k-client.rb

Planned

• details responses
• make available the node's attributes (cpu, memory, etc.)
• choice: do we settle on using a REST architectural style ?
• experiment submission