Table of Contents

Student and mentor ;), please read carefully this page…

Student: Jean-Pierre POUTCHEU

Mentor: Bruno Bzeznik

Co-Mentor: Olivier Richard


Student: Things to do before starting

Project Specification

(add details here)

Pagination specifications

  /jobs.(yaml|json|html)
  /jobs/details.(yaml|json|html)
  /jobs/table.(yaml|json|html)
  /jobs.(yaml|json|html)?start_id=X
  /jobs/details.(yaml|json|html)?start_id=X
  /jobs/table.(yaml|json|html)?start_id=X
   items ==> jobs results (hashmap if structure = oar, table if structure = simple)
   page ==> current page number in the results list, used in the next and previous links generation
   limit ==> limit value (this value overwrite the value defined in the OAR file config)
   [[next_url_link|==> the next url link]]   e.g. "/jobs.(yaml|json|html)?start_id=X&page=3"
   [[previous_url_link|==> the previous url link]]  e.g. "/jobs.(yaml|json|html)?start_id=X&page=1"
   'next_url_link' and 'previous_url_link' may be absent
    struct_job_list(jobs, structure, previous_url_link, next_url_link)
    struct_job_list_details(jobs, structure, previous_url_link, next_url_link)
    'previous_url_link' and 'next_url_link' will be added as parameters

Pagination specifications (Bruno version)

Every data structure returned by the API should be wrapped into this hash table:

 items ==> query results (hashmap if structure = oar, table if structure = simple)
 limit ==> limit value (this value overwrite the value defined in the OAR file config)
 offset ==> id at which the listing started
 total ==> total number of items
 links ==> array of hash describing useful links: href => <uri> , rel => <self|parent|...>
  We know that we have a next page if :
    (# of items) + offset < total
  or if there's a link->rel=="next"
 key1=>value1
 key2=>value2
 ...
 links ==> array of hash describing useful links: href => <uri> , rel => <self|parent|...>

Specific case of the jobs uri (as an example of an uri that needs pagination):

  GET /jobs[[/details|/table]].(yaml|json|html)?[[from=<FROM>]]&[to=<TO>]&[[state=<STATE>]]&[offset=<ID>]&[[limit=<LIMIT>]]
  FROM: From unix timestamp
  TO: To unix timestamp
  STATE: List of possible states (ex: Running,Waiting,Finishing,Launching)
  ID: the first id to be listed. Jobs are listed from this id until LIMIT is reached
  LIMIT: if more than LIMIT jobs satisfy the query, stop when this LIMIT is reach

input/output Examples

 items:
   - api_timestamp: 1276689144
     id: 11
     name: ~
     owner: kameleon
     queue: default
     state: Running
     submission: 1276689106
     links:
       - href: /jobs/11
         rel: self
       - href: /jobs/11/resources
         rel: resources
   - api_timestamp: 1276689144
     id: 12
     name: ~
     owner: kameleon
     queue: default
     state: Running
     submission: 1276689109
     links:
       - href: /jobs/12
         rel: self
       - href: /jobs/12/resources
         rel: resources
 total: 5
 offset: 0
 links:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2
     rel: self
   # Optional:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=2
     rel: next
 items:
   - api_timestamp: 1276689144
     id: 13
     name: ~
     owner: kameleon
     queue: default
     state: Running
     submission: 1276689106
   - api_timestamp: 1276689144
     links:
       - href: /jobs/13
         rel: self
       - href: /jobs/13/resources
         rel: resources
     id: 14
     name: ~
     owner: kameleon
     queue: default
     state: Running
     submission: 1276689109
     links:
       - href: /jobs/14
         rel: self
       - href: /jobs/14/resources
         rel: resources
 total: 5
 offset: 2
 links:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=2
     rel: self
   # Optional:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=4
     rel: next
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=0
     rel: prev
 items:
   - api_timestamp: 1276689144
     id: 15
     name: ~
     owner: kameleon
     queue: default
     state: Running
     submission: 1276689106
     links:
       - href: /jobs/15
         rel: self
       - href: /jobs/15/resources
         rel: resources
 total: 5
 offset: 4
 links:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=4
     rel: self
   # Optional:
   - href: /jobs.yaml?from=1274096990&to=1276688990&limit=2&offset=2
     rel: prev

Default uri parameters

 # Maximum default number of items
 API_NUMBER_ITEMS_LIMIT
 # Default parameters for the /jobs uri
 # if a "&limit=" is given, the $API_NUMBER_ITEMS_LIMIT is ignored for this uri
 API_JOBS_URI_DEFAULT_PARAMS="Finishing,Running,Resuming,Suspended,Launching,toLaunch,Waiting,toAckReservation,Hold&limit=200

Oaradmin api specifications

Admission rules

;<s>GET /admission_rules</s>

list admissions rules

;<s>GET /admission_rules/<id></s>

list the admission rule #id:
 id: 1
 rule: |
       code line 1
       code line 2
       .... 
 links:
    - href ======
      rel=current

;<s>PUT /admission_rules</s>

create a new admission rule
 #PUTDATA:
  rule: |
       code line 1
       code line 2
       ....

;<s>POST /admission_rules</s>

create a new admission rule (for browsers compatibility)
 #POSTDATA:
 method: put
 rule: |
       code line 1
       code line 2
       ....

;<s>DELETE /admission_rules/<id></s>

delete an admission rule

;<s>POST /admission_rules/<id></s>

delete an admission rule (for browsers compatibility)
 #POSTDATA:
  method: delete
erase an admission rule
 #POSTDATA:
  rule: |
       code line 1
       code line 2
       ....

Resources creation

 #POSTDATA:
  <s>param  = '-a /node=node1 -p memnode=1024 -p cpufreq=3.2 -p cputype=xeon'</s>
  resources: '/node=node{4}/cpu={2}/core={2}'
  properties:
            memnode: 1024
            cpufreq: '3.2'
            cputype: 'xeon'
          
*  RESULT
 <s>ressources:
     - hostname : node1
       properties :
             - memnode : 1024
               cpufreq : 3.2
               cputype : xeon
       ....
       .... </s>  
 items:
      - hostname : node1
        properties :
                   cpu: 1
                   core: 1
                   cpuset: 0
                   memnode : 1024
                   cpufreq : 3.2
                   cputype : xeon
      - hostname : node1
        properties :
                   cpu: 1
                   core: 2
                   cpuset: 1
                   memnode : 1024
                   cpufreq : 3.2
                   cputype : xeon
       ...
 links : 
       - rel : create
         method : post
         url : /resources
       - rel : self
         method : post
         url : /resources/generate

Configuration variables (oar.conf)

; <s>GET /config.(yaml|json|html)</s>

Get all the configuration variables
 #Example output:
  DB_TYPE: 'mysql'
  DB_HOSTNAME: 'localhost'
  DB_PORT: '3306'
  ...

; <s>GET /config/<variable_name>.(yaml|json|html)</s>

Get a variable
 # Example query:
  GET /config/DB_TYPE.yaml
 # output:
  DB_TYPE: 'mysql'
  api_timestamp: 1278574909
  links:
       - rel: set
         method: post
         url: /config/DB_TYPE
       - rel: self
         method: get
         url: /config/DB_TYPE

; <s>POST /config/<variable_name>.(yaml|json|html)</s>

Set a variable
 # example QUERY
  POST /config/DB_TYPE.yaml
 # example POSTDATA
  value: "mysql"

; <s>POST /config.(yaml|json|html)</s>

Set all the configuration variables
 # example QUERY
  POST /config.yaml
 # example POSTDATA
  DB_TYPE: 'mysql'
  DB_HOSTNAME: 'localhost'
  DB_PORT: '3306'
  ...

Do we make checks??? Mandatory variables; types; syntax;?

Main Milestones

Tips

TODO list

Mentor

Student