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.

REST API

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]

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]

site's details

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

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]

host's details

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

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

XML-RPC API

Experimental feature. This is mainly an auto-generated wrapper on top of the REST API. This requires an XML-RPC library that supports HTTP Basic Authentication.

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

sites.index()

list of sites (cached for 1 hour). Same response format as for JSON response.

sites.show(site_uid:string)

site's details

hosts.index(site_uid:string)

list of site's hosts (cached for 90 seconds) with their states. Same response format as for JSON response.

hosts.show(site_uid:string, host_uid:string)

host's detail

clusters.index(site_uid:string)

list of site's clusters. Same response format as for JSON response.

Getting Started

Ruby client (REST API)

Put this code in a g5k-rest-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-rest-client.rb

Ruby client (XML-RPC API)

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

 require 'xmlrpc/client'
 require 'pp'
 server = XMLRPC::Client.new3( :host => "helpdesk.grid5000.fr", 
                               :path => "/api/rennes/xmlrpc", 
                               :user => "G5Klogin", 
                               :password => "G5Kpassword", 
                               :use_ssl => true, 
                               :timeout => 5 )
 begin
   sites_response = server.call("sites.index") # equivalent to GET /sites
   sites_response['items'].each do |site|
     puts "------------------ #{site['uid']} ------------------"
     puts "Clusters = [#{site['clusters'].map{|cluster| cluster['uid']}.join(", ")}]"
 
     # get the site's nodes. we need to know the RPC call before runtime to get new information
     hosts_response = server.call("hosts.index", site['uid']) # equivalent to GET /sites/{site_uid}/hosts
     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 XMLRPC::FaultException => e
   puts "Error:"
   puts e.faultCode
   puts e.faultString
 end

Run with:

 ruby g5k-xmlrpc-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