User REST API¶
The OAR REST API allows to interact with OAR over http using a REST library. Most of the operations usually done with the oar Unix commands may be done using this API from your favourite language.
Concepts¶
Access¶
A simple GET query to the API using wget may look like this:
# Get the list of resources
wget -O - http://www.mydomain.org/oarapi/resources.yaml?structure=simple
You can also access to the API using a browser. Make it point to http://www.myoarcluster.local/oarapi/index.html and you’ll see a very simple HTML interface allowing you to browse the cluster resources, post a job using a form or even create resources if you are a OAR administrator. (of course, replace www.myoarcluster.local by a valid name allowing you to join the http service of the host where the API is installed).
But generally, you’ll use a REST client or a REST library provided for your favorite language. You’ll see examples using a ruby rest library in the next parts of this document.
Check your system administrator to know on which URI the OAR API is installed.
Authentication¶
Most of the time, you’ll make requests that needs you to be authenticated. The way you are authenticated depends on what your local admistrator configured. There’s almost as many possibilities as what Apache (the http server used by this API) may manage. The simplest method is a “Basic authentication” with a login/password. It may be binded to a local directory (for example LDAP). You may also find an “ident” based authentication that guesses automatically your login from a little daemon running on your client host. If the “ident” method is used, your unix login is automatically used. But as only a few hosts may be trusted, you’ll probably have to open a tunnel to one of this host. You may use ssh to do this. For example, supposing access.mycluster.fr is a gateway host trusted by the api host:
$ ssh -NL 8080:api.mycluster.fr:80 login@access.mycluster.fr
Then, point your REST client to::
# http://localhost:8080
Formats and data structure types¶
The API currently can serve data into YAML, JSON or HTML. Posted data can also be coded into YAML, JSON or x-www-form-urlencoded (for HTML from posts). You may specify the requested format by 2 ways:
- giving an extension to resources: .yaml, .json or .html
- setting the HTTP_ACCEPT header variable to text/yaml, application/json or text/html
For the posted data, you have to correctly set the HTTP_CONTENT_TYPE variable to text/yaml, application/json or application/x-www-form-urlencoded.
Sometimes, the data structures returned (not the coding format, but the contents: array, hashes, array of hashes,…) may be changed. Currently, we have 2 available data structure types: simple and oar. The structure is passed through the variable structure that you may pass in the url, for example: ?structure=simple
- The simple data structure tries to be as simple as possible, using simple arrays in place of hashes wherever it is possible
- The oar data structure serves data in the way oar does with the oarnodes/oarstat export options (-Y, -D, -J,…) Be aware that this data structure is not meant to be maintained since 2.5 release of OAR. The simple data structure is highly recommended.
By default, we use the simple data structure.
Here are some examples, using the ruby restclient (see next section):
# Getting resources infos
# in JSON
irb(main):004:0> puts get('/resources.json')
# in YAML
irb(main):005:0> puts get('/resources.yaml')
# Same thing
irb(main):050:0> puts get('/resources', :accept=>"text/yaml")
# Specifying the "oar" data structure
irb(main):050:0> puts get('/resources.json?structure=oar')
# Specifying the "simple" data structure
irb(main):050:0> puts get('/resources.json?structure=simple')
Errors and debug¶
When the API returns an error, it generally uses a standard HTTP return status (404 NOT FOUND, 406 NOT ACCEPTABLE, …). But it also returns a body containing a hash like the following:
{
"title" : "ERROR 406 - Invalid content type required */*",
"message" : "Valid types are text/yaml, application/json or text/html",
"code" : "200"
}
This error body is formated in the requested format. But if this format was not given, it uses JSON by default.
To allow you to see the error body, you may find it useful to activate the debug=1 variable. It will force the API to always return a 200 OK status, even if there’s an error so that you can see the body with a simple browser or a rest client without having to manage the errors. For example:
wget -nv -O - "http://localhost:8080/oargridapi/sites/grenoble?debug=1"
Here is an example of error catching in ruby:
# Function to get objects from the api
# We use the JSON format
def get(api,uri)
begin
return JSON.parse(api[uri].get(:accept => 'application/json'))
rescue => e
if e.respond_to?('http_code')
puts "ERROR #{e.http_code}:\n #{e.response.body}"
else
puts "Parse error:"
puts e.inspect
end
exit 1
end
end
Ruby REST client¶
One of the easiest way for testing this API is to use the rest-client ruby module:
http://rest-client.heroku.com/rdoc/
It may be used from ruby scripts (http://www.ruby.org/) or interactively. It is available as a rubygem, so to install it, simply install rubygems and do “gem install rest-client”. Then, you can run the interactive client which is nothing else than irb with shortcuts. Here is an example irb session:
$ export PATH=$PATH:/var/lib/gems/1.8/bin
$ restclient http://localhost/oarapi
irb(main):001:0> puts get('/jobs.yaml')
---
- api_timestamp: 1246457384
id: 551
name: ~
owner: bzizou
queue: besteffort
state: Waiting
submission: 1245858042
uri: /jobs/551
=> nil
irb(main):002:0>
or, if an http basic auth is required:
restclient http://localhost/api <login> <password>
...
Pagination and common rules into output data¶
Results served by the API are mainly of 2 kinds: “items” and “collections”. A collection is actually an array of items. Some uris serve collections that may have a very big amount of items (for example all the terminated jobs of a cluster). For that reason, collections are often “paginated”. It means that the collections are presented into pages that have got meta data to give you informations about offset, numbers, and links to previous/next page. Furthermore, items are often composed of commonly used kind of data, especially ‘id’ and ‘links’. We have tried to normalize this as much as possible, so, here is a description of the common properties of items and collections:
Items¶
Items have the following features:
Hash: | Items should be hashes (sometimes hash of hashes for the ‘oar’ data structure, but it is to be avoided) |
---|---|
the ‘id’ key: | In general, when an item may be uniquely identified by an integer, it is given in the “id” key. Note that OAR nodes are identified by the ‘network_address’ key that is an integer, but this is an exception. |
the ‘links’ array: | |
Items, especially when listed in a collection, often give links to more informations or relative data. The links are listed in the links array. Each element of this array (a link) is composed of at least: a ‘rel’ key and a ‘href’ key. The ‘rel’ key is a string telling what is the relation between the current item and the resource pointed by the link. The ‘href’ key is a string giving the URI of the link relative to the root of the API. It’s possible that other keys will be implemented in the future (for example a ‘title’ key.) Common values for ‘rel’ are: ‘self’, ‘parent’, ‘next’, ‘previous’. | |
the ‘api_timestamp’ value: | |
Each item has a ‘api_timestamp’ key giving the epoch unix date at which the API constructed the item. This field may be omitted when items are listed inside a collection; then the collection has a global api_timestamp value. This date is given in the timezone provided by the “GET /timezone uri”. |
Collections¶
Collections have the following features:
the ‘items’ array: | |
---|---|
The items array is the purpose of a collection. It lists all the items of the current page of a collection. | |
the ‘total’ number: | |
It’s an integer giving the total number of items in the collection. If the items array contains less elements than this number, then the collection has been paginated and a ‘next’ and/or ‘previous’ link should be provided. | |
the ‘offset’ number: | |
It gives the offset at which the paginated list starts. If 0, then, it is the first page. | |
the ‘limit’ parameter: | |
This is not in the output, but a parameter common to all paginable uris. If you specify a limit, then it gives the size of the pages. | |
the ‘links’ array: | |
For a collection, the links array often gives the uri of the next/previous page. But it also gives the uri of the current page (‘self’) and may point to more informations relative to this collection. See the links array description from above for items, it is similar for the collection. |
Examples¶
- An item looks like this (yaml output):
api_timestamp: 1286894740 available_upto: 2147483646 besteffort: YES core: 1 cpu: 1 cpuset: 0 deploy: NO desktop_computing: NO expiry_date: 0 finaud_decision: NO id: 1 last_available_upto: 0 last_job_date: 1286885902 links: - href: /resources/nodes/fake1 rel: node - href: /resources/1 rel: self - href: /resources/1/jobs rel: jobs network_address: fake1 next_finaud_decision: NO next_state: UnChanged resource_id: 1 scheduler_priority: 0 state: Alive state_num: 1 suspended_jobs: NO type: default
- A collection looks like this (yaml output):
api_timestamp: 1286894823 items: - api_timestamp: 1286894823 id: 2 links: - href: /jobs/2 rel: self - href: /jobs/2/resources rel: resources name: ~ owner: kameleon queue: default state: Error submission: 1284034267 - api_timestamp: 1286894823 id: 3 links: - href: /jobs/3 rel: self - href: /jobs/3/resources rel: resources name: ~ owner: kameleon queue: default state: Error submission: 1284034383 links: - href: /jobs.yaml?state=Error&limit=2&offset=0 rel: self - href: /jobs.yaml?state=Error&limit=2&offset=2 rel: next offset: 0 total: 2623
REST requests description¶
Examples are given in the YAML format because we think that it is the more human readable and so very suitable for this kind of documentation. But you can also use the JSON format for your input/output data. Each resource uri may be postfixed by .yaml, .jso of .html.
- In this section, we describe every REST resources of the OAR API. The authentication may be:
- public: everybody can query this resource
- user: only authenticated and valid users can query this resource
- oar: only the oar user can query this resource (administration usage)
GET /index¶
description: | Home page for the HTML browsing |
---|---|
formats: | html |
authentication: | public |
output: |
|
note: | Header of the HTML resources may be customized into the /etc/oar/api_html_header.pl file. |
GET /version¶
description: | Gives version informations about OAR and OAR API. Also gives the timezone of the API server. |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: |
|
usage example: | wget -q -O - http://localhost/oarapi/version.yaml
|
GET /whoami¶
description: | Gives the name of authenticated user seen by OAR API. The name for a not authenticated user is the null string. |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: |
|
usage example: | wget -q -O - http://localhost/oarapi/whoami.yaml
|
GET /timezone¶
description: | Gives the timezone of the OAR API server. The api_timestamp given in each query is an UTC timestamp (epoch unix time). This timezone information allows you to re-construct the local time. |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: | structure: hash
|
usage example: | wget -q -O - http://localhost/oarapi/timezone.yaml
|
GET /jobs¶
description: | List jobs (by default only the jobs in queue) |
---|---|
formats: | html , yaml , json |
authentication: | public |
parameters: |
|
output: | structure: collection
|
note: | The “rel: resources” link of a job lists the assigned or reserved resources of a job. |
usage example: | wget -q -O - http://localhost/oarapi/jobs.yaml?state=Terminated,Running&limit=2&offset=48"
|
GET /jobs/details¶
description: | Same as /jobs, but with more details and “resources” and “nodes” links developped. |
---|---|
formats: | html , yaml , json |
authentication: | public |
parameters: |
|
output: | structure: collection
|
- usage example:
wget -q -O - http://localhost/oarapi/jobs/details.yaml
GET /jobs/table¶
description: | Same as /jobs but outputs the data of the SQL job table |
---|---|
formats: | html , yaml , json |
authentication: | public |
parameters: |
|
output: | structure: collection
note: Field names may vary from the other job lists because this query results more like a dump of the jobs table. |
usage example: | wget -q -O - http://localhost/oarapi/jobs/table.yaml
|
GET /jobs/<id>[/details]¶
description: | Get infos about the given job. If /details is appended, it gives more informations, such as the expanded list of resources allocated to the job. |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | wget --user test --password test -q -O - http://localhost/oarapi/jobs/547.yaml
|
GET /jobs/<id>/resources¶
description: | Get resources reserved or assigned to a job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | public |
output: | structure: hash
|
usage example: | wget -q -O - http://localhost/oarapi/jobs/547/resources.yaml
|
POST /jobs/<id>/deletions/new¶
description: | Deletes a job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/567/deletions/new.yaml','')
|
POST /jobs/<id>/checkpoints/new¶
description: | Send the checkpoint signal to a job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/568/checkpoints/new.yaml','')
|
POST /jobs/<id>/holds/new¶
description: | Asks to hold a waiting job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/560/holds/new.yaml','')
|
POST /jobs/<id>/rholds/new¶
description: | Asks to hold a running job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/560/rholds/new.yaml','')
|
POST /jobs/<id>/resumptions/new¶
description: | Asks to resume a holded job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/560/resumptions/new.yaml','')
|
POST /jobs/<id>/signals/<signal>¶
description: | Asks to resume a holded job |
---|---|
parameters: |
|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash
|
usage example: | irb(main):148:0> puts post('/jobs/560/signals/12.yaml','')
|
POST /jobs¶
description: | Creates (submit) a new job |
---|---|
formats: | html , yaml , json |
authentication: | user |
input: | Only [resource] and [command] are mandatory. Please, refer to the documentation of the oarsub command for the resource syntax which correspond to the -l (–resource) option. structure: hash with possible arrays (for options that may be passed multiple times)
|
output: | structure: hash
note: more informations about the submited job may be obtained with a GET on the provided uri. |
usage example: | # Submitting a job using ruby rest client
irb(main):010:0> require 'json'
irb(main):012:0> j={ 'resource' => '/nodes=2/cpu=1', 'command' => '/usr/bin/id' }
irb(main):015:0> job=post('/jobs' , j.to_json , :content_type => 'application/json')
# Submitting a job with a provided inline script
irb(main):024:0> script="#!/bin/bash
irb(main):025:0" echo \"Hello world\"
irb(main):026:0" whoami
irb(main):027:0" sleep 300
irb(main):028:0" "
irb(main):029:0> j={ 'resource' => '/nodes=2/cpu=1', 'script' => script , 'workdir' => '~bzizou/tmp'}
irb(main):030:0> job=post('/jobs' , j.to_json , :content_type => 'application/json')
|
POST /jobs/<id>¶
description: | Updates a job. In fact, as some clients (www browsers) doesn’t support the DELETE method, this POST resource has been created mainly to workaround this and provide another way to delete a job. It also provides checkpoint, hold and resume methods, but one should preferably use the /checkpoints, /holds and /resumptions resources. |
---|---|
formats: | html , yaml , json |
authentication: | user |
input: | structure: hash {“action” => “delete”}
|
output: | structure: hash
|
usage example: | # Deleting a job in the ruby rest client
puts post('/jobs/554.yaml','{"method":"delete"}',:content_type => "application/json")
|
DELETE /jobs/<id>¶
description: | Delete or kill a job. |
---|---|
formats: | html , yaml , json |
authentication: | user |
output: | structure: hash returning the status
|
usage example: | # Deleting a job in the ruby rest client
puts delete('/jobs/554.yaml')
|
note: | Not all clients support the DELETE method, especially some www browsers. So, you can do the same thing with a POST of a {“method”:”delete”} hash on the /jobs/<id> resource. |
GET /jobs/form¶
description: | HTML form for posting (submiting) new jobs from a browser |
---|---|
formats: | html |
authentication: | user |
output: |
|
note: | This form may be customized in the /etc/oar/api_html_postform.pl file |
GET /resources¶
description: | Get the list of resources and their state |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: | structure: hash
note: More details about a resource can be obtained with a GET on the provided uri. The list of all the resources of the same node may be obtained with a GET on node_uri. The list of running jobs on a resource can be obtained with a GET on the jobs_uri resource. note: The following parameters can be passed through the requested URL
|
usage example: | wget -q -O - http://localhost/oarapi/resources.yaml
|
GET /resources/details¶
description: | Get the list of resources and all the details about them |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: | structure: hash
|
usage example: | wget -q -O - http://localhost/oarapi/resources/details.yaml
*note*: The following parameters can be passed through the requested URL
- limit : limit of resources to be shown per page
- offset : the page result offset
|
GET /resources/<id>¶
description: | Get details about the resource identified by id |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: | structure: 1 element array of hash
|
usage example: | wget -q -O - http://localhost/oarapi/resources/1.yaml
|
GET /resources/nodes/<network_address>¶
description: | Get details about the resources belonging to the node identified by network_address |
---|---|
formats: | html , yaml , json |
authentication: | public |
output: | structure: array of hashes
|
usage example: | wget -q -O - http://localhost/oarapi/resources/nodes/liza-1.yaml
|
POST /resources/generate¶
description: | Generates (outputs) a set of resources using oaradmin. The result may then be directly sent to /resources for actual creation. |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | [resources] and [properties] entries are mandatory structure: hash describing the resources to generate
|
output: | structure: an array of hashes containing the generated resources that may be pushed to POST /resources for actual creation
|
usage example: | # Generating new resources with curl
curl -i -X POST http://oar:kameleon@localhost/oarapi-priv/resources/generate -H'Content-Type: application/json' -d '{"resources":"/nodes=node{2}.test.generate/cpu={2}/core={2}"}'
|
POST /resources¶
description: | Creates a new resource or a set of new resources |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | A [hostname] or [network_address] entry is mandatory structure: A hash describing the resource to be created. An array of hashes may be given for creating a set of new resources. The result of a /resources/generate query may be directly posted to /resources.
|
output: | structure: hash returning the id of the newly created resource and status (or an array of hashes if a set of resources has been given on the input)
|
usage example: | # Adding a new resource with the ruby rest client (oar user only)
irb(main):078:0> r={ 'hostname'=>'test2', 'properties'=> { 'besteffort'=>'NO' , 'cpu' => '10' } }
irb(main):078:0> puts post('/resources', r.to_json , :content_type => 'application/json')
|
POST /resources/<id>/state¶
description: | Change the state |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | A [state] entry is mandatory and must be “Absent”, “Alive” or “Dead” structure: hash of state
|
output: | structure:
|
usage example: | irb
|
DELETE /resources/<id>¶
description: | Delete the resource identified by id |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: hash returning the status
|
usage example: | # Deleting a resource with the ruby rest client
puts delete('/resources/32.yaml')
|
note: | If the resource could not be deleted, returns a 403 and the reason into the message body. |
DELETE /resources/<node>/<cpuset_id>¶
description: | Delete the resource corresponding to cpuset_id on node node. It is useful when you don’t know about the ids, but only the number of cpus on physical nodes. |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: hash returning the status
|
usage example: | # Deleting a resource with the ruby rest client
puts delete('/resources/test/0.yaml')
|
note: | If the resource could not be deleted, returns a 403 and the reason into the message body. |
GET /admission_rules¶
description: | Get the list of admission rules |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: hash
|
usage example: | wget -q -O - http://localhost/oarapi/admission_rules.yaml
*note*: The following parameters can be passed through the requested URL
- limit : limit of admission rules to be shown per page
- offset : the page result offset
|
GET /admission_rules/<id>¶
description: | Get details about the admission rule identified by id |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: 1 element array of hash
|
usage example: | wget -q -O - http://localhost/oarapi/admission_rules/1.yaml
|
DELETE /admission_rule/<id>¶
description: | Delete the admission rule identified by id |
||
---|---|---|---|
formats: | html , yaml , json |
||
authentication: | oar |
||
output: | structure: hash returning the status
|
||
usage example: | # Deleting an admisssion rule with the ruby rest client
puts delete('/admission_rules/32.yaml')
|
||
note: |
|
POST /admission_rules¶
description: | Add a new admission rule |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | structure: hash
|
output: | A 201 (created) header is returned if the rule is successfully created, with a location value.
|
POST /admission_rules/<id>¶
description: | Update or delete the admission rule given by id |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | structure: hash
|
output: | A 201 (created) header is returned if the rule is successfully updated, with a location value.
|
GET /config¶
description: | Get the list of configured variables |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: array of hashes
|
usage example: | curl -i -X GET http://login:password@localhost/oarapi-priv/config.yaml
|
GET /config/file¶
description: | Get the raw config file of OAR. It also output the path of the file used by the API. |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: hash
|
usage example: | curl -i -X GET http://kameleon:kameleon@localhost/oarapi-priv/config/file.yaml
|
GET /config/<variable>¶
description: | Get details about the configuration variable identified by variable |
---|---|
formats: | html , yaml , json |
authentication: | oar |
output: | structure: 1 element array of hash
|
usage example: | curl -i -X GET http://login:password@localhost/oarapi-priv/config/DB_TYPE.yaml
|
POST /config/<variable>¶
description: | Change the value of the configuration variable identified by variable |
---|---|
formats: | html , yaml , json |
authentication: | oar |
input: | A [value] entry is mandatory structure: hash describing the new value of the variable
|
output: | structure: hash returning the variable and his new value
|
usage example: | curl -i -X POST http://login:password@localhost/oarapi-priv/config/API_JOBS_URI_DEFAULT_PARAMS.yaml -H'Content-Type: text/yaml' -T config.yaml
|
note: | config.yaml contains the value of the variable. |
GET /media/ls/<file_path>¶
description: | Get a list of the directory from the path given by file_path. The file_path may contain the special character “~” that is expanded to the home directory of the user that is making the request. |
---|---|
formats: | html , yaml , json |
authentication: | user |
output: | structure: array of hashes giving for each listed file: the name, the mode, the size, the modification time and the type (f for a file or d for a directory)
|
usage example: | curl -i -X GET http://kameleon:kameleon@localhost/oarapi-priv/media/ls/~/ -H'Content-Type: text/yaml'
|
note: | returns a 404 if the path does not exist, or a 403 if the path is not readable. Errors in debug mode (with ?debug=1) are formated into yaml. |
GET /media/<file_path>¶
description: | Get a file located on the API host, into the path given by file_path. The file_path may contain the special character “~” that is expanded to the home directory of the user that is making the request. |
---|---|
parameters: |
|
formats: | application/octet-stream |
authentication: | user |
output: | octet-stream |
usage example: | curl -i -H'Content-Type: application/octet-stream' http://kameleon:kameleon@localhost/oarapi-priv/media/~/cigri-3/CHANGELOG
|
note: | returns a 404 if the file does not exist, or a 403 if the file is not readable. Errors in debug mode (with ?debug=1) are formated into yaml. |
POST /media/<file_path>¶
description: | Upload or create a file on the API host, into the path given by file_path. The file_path may contain the special character “~” that is expanded to the home directory of the user that is making the request. If the path does not exists, the directories are automatically created. If no data is passed, an empty file is created. If binary data is sent as POSTDATA, then it is a file to upload. |
---|---|
formats: | application/octet-stream |
authentication: | user |
output: | 201 if ok |
usage example: | curl -i -X POST -H'Content-Type: application/octet-stream' --data-binary @/etc/group http://kameleon:kameleon@localhost/oarapi-priv/media/~/testdir/testfile
|
POST /media/chmod/<file_path>¶
description: | Changes the permissions on a file: do a chmod(1) on file_path. The special character “~” is expanded as the home of the user that makes the query. |
---|---|
formats: | html , yaml , json |
authentication: | user |
input: | A [mode] entry is mandatory mode: A mode definition as passed to the “chmod” unix command. |
output: | 202 if ok |
usage example: | curl -i -X POST http://kameleon:kameleon@localhost/oarapi-priv/media/chmod/~/param9 -H'Content-Type: application/json' -d '{"mode":"755"}'
|
DELETE /media/<file_path>¶
description: | Delete the file or directory given by file_path. The file_path may contain the special character “~” that is expanded to the home directory of the user that is making the request. If the path is a directory, then it is deleted recursively. |
---|---|
formats: | application/octet-stream |
authentication: | user |
output: | 204 if ok |
usage example: | curl -i -X DELETE -H'Content-Type: application/octet-stream' http://kameleon:kameleon@localhost/oarapi-priv/media/~/testdir
|
GET /colmet/job/<id>¶
description: | Extract colmet data for a given job. Colmet should be installed and the colmet-collector should dump data into hdf5 files located in the API_COLMET_HDF5_PATH_PREFIX specified into the oar.conf file. The served data is provided as a gzip compressed file containing a JSON hash with a key for each metric. The “hostname” and “timestamp” metrics are always appended, even if not specified. |
---|---|
parameters: |
|
formats: | application/x-gzip |
authentication: | user |
output: | Gzip compressed JSON data |
usage example: | curl -H'Content-Type: application/x-gzip' "http://localhost/oarapi/colmet/job/5767965?from=1427780621&to=1427899621" > 5767965.json.gz
|
Some equivalences with oar command line¶
OAR command | REST request |
---|---|
oarstat | GET /jobs.html |
oarstat -Y | GET /jobs/details.yaml |
oarstat -Y -j <id> | GET /jobs/<id>.yaml |
oarstat -Y -fj <id> | GET /jobs/<id>/details.yaml |
oardel <id> | DELETE /jobs/<id>.yaml |
oardel <id> (alternative way) | POST /jobs/deletions/<id>/new.yaml |
oarnodes -Y | GET /resources/details.yaml |
oarnodes -Y -r1 | GET /resources/1.yaml |