User Tools

Site Tools


Sidebar

Overview

Navigation

Scenarios

Components

Manuals

  • Basic components
  • Application support
  • Additional components
    • manual:restif

      REST interface for the 3G Bridge

      This manual describes the use and configuration of the 3G Bridge REST interface.

      User Guide

      The REST interface is an alternative to the SOAP based interface, with similar functionalities. The only limitation is that local files cannot be specified as input files when submitting a job; only remote file specifications are possible. Aside from this, the REST interface is a superset of the SOAP interface.

      In this manual, we assume that the project URL is http://example.com/myproject/, and the REST interface is deployed in download/wss/. That is, the base URL of the REST interface is http://example.com/myproject/download/wss/.

      General options

      A requested entity or collection will respond with a table (list of associative arrays). This response will be rendered according to the format argument, which can be plain, html or json. The hdr argument enables (1) or disables (0) the rendering of a header if applicable. The default format is plain.

      • plain: The response will be rendered as plain text. Records are separated with '\n', attributes are separated with a single space. Separators can be overridden with the sep and rsep (record sepatator) arguments. A header is rendered if requested (hdr=1).
      • html: The response is rendered as a HTML table. A header is rendered by default.
      • json: The response is rendered as a JSON string.

      Example:

      http://example.com/myproject/download/wss/version
      3G Bridge 1.9
      http://example.com/myproject/download/wss/version?hdr=1
      version
      3G Bridge 1.9
      http://example.com/myproject/download/wss/version?format=json
      [{"version":"3G Bridge 1.9"}]

      For plain format, the field separator can be overridden with the sep argument. The record separator can be overridden with rsep.

      http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d?sep=|
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d|Cloud|cloud|CANCEL||--image=ami-00000021|||2012-09-11 11:20:06|

      For most entities (not collections), specific attributes can be selected in the URL:

      http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d/id+status+creation_time
      93fd32b-4604-4c06-9ba9-d3aae7a6b80d CANCEL 2012-09-11 11:20:06

      Entities

      Most entities only support the GET verb. If not stated otherwise, the following output examples are the results of GET requests on the specified entities.

      Querying the version of the Bridge

      http://example.com/myproject/download/wss/version
      3G Bridge 1.9

      SOAP equivalent:

      wsclient -m version -e http://example.com:8091/

      Querying queues

      Querying available queues
      http://example.com/myproject/download/wss/queues
      Cloud audiveris 1
      edgidemo audiveris 1 
      edgidemo bwa-boinc 1
      NULL dsp
      MetaJob dsp
      ...

      SOAP equivalent: —

      Querying available grids
      http://example.com/myproject/download/wss/grids
      Cloud
      edgidemo
      MetaJob
      NULL

      SOAP equivalent: —

      Querying available algorithms for a grid
      1. All attributes:
        http://example.com/myproject/download/wss/grids/edgidemo
      2. Only algorithm names:
        http://example.com/myproject/download/wss/grids/edgidemo/alg
      edgidemo audiveris 1 
      edgidemo bbgc 1 
      edgidemo Blender 1 
      edgidemo bwa-boinc 1
      ...

      SOAP equivalent for 2nd case:

      wsclient -m gridalgs -e http://example.com:8091/ -g edgidemo

      Managing jobs

      Querying all jobs
      http://example.com/myproject/download/wss/jobs?hdr=1
      id grid alg status gridid args griddata tag creation_time metajobid
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d Cloud cloud CANCEL  --image=ami-00000021   2012-09-11 11:20:06 
      0bba95f9-38ea-4cf9-8125-6bc3e93af154 Cloud cloud CANCEL  --image=ami-00000021   2012-09-13 10:40:07
      ...

      SOAP equivalent: —

      Querying a single job
      http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d Cloud cloud CANCEL  --image=ami-00000021   2012-09-11 11:20:06

      Any subset of the attributes can be selected. Consider the following SOAP commands:

      wsclient -m status -e http://example.com:8091/ -j 093fd32b-4604-4c06-9ba9-d3aae7a6b80d

      REST equivalent:

      http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d/id+status
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d CANCEL
      wsclient -m griddata -e http://example.com:8091/ -j 093fd32b-4604-4c06-9ba9-d3aae7a6b80d

      REST equivalent:

      http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d/id+griddata
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d d2048dd6-464e-47c9-a4d0-373a9de25bdb_e933a6f8-7365-4b58-846d-a38be7d4ba24_76a26b38-88fd-4ba3-912b-2b1e30ed74d6
      Querying finished jobs
      http://example.com/myproject/download/wss/jobs/finished/id+status
      093fd32b-4604-4c06-9ba9-d3aae7a6b80d FINISHED
      0bba95f9-38ea-4cf9-8125-6bc3e93af154 ERROR
      0f25e8cb-45f6-4f7f-83b4-4525dc245b11 FINISHED

      SOAP equivalent:

      wsclient -m finished -e http://example.com:8091/
      Cancelling a job or deleting a finished job

      To cancel a job, send a request to its URL with the DELETE verb.

      curl -X DELETE  http://example.com/myproject/download/wss/jobs/093fd32b-4604-4c06-9ba9-d3aae7a6b80d

      SOAP equivalent:

      wsclient -m delete -e http://example.com:8091/ -j 093fd32b-4604-4c06-9ba9-d3aae7a6b80d
      Submitting a job

      A job can be submitted to the Bridge by POSTing a job object to the jobs entity. Currently, there are two ways to do this; either by posting form-data (Content-Type: application/x-www-form-urlencoded) or by posting a JSON object (application/json). The following examples show how this can be achieved using curl.

      In both cases, by default, after a successful submission, the Bridge will respond with a redirect header to the newly created jobs (Location: http://example.com/myproject/download/wss/jobs/<new_uuid>). The -L switch tells curl to follow this redirection.

      Another possibility is to specify 'redir=0' in the URL (…/wss/jobs?redir=0); in this case, no redirection occurs, only the unique id of the new job is printed. This is the same behaviour as that of the SOAP interface.

      To submit a job, the same information has to be supplied as in case of the SOAP interface. Notice that—unlike the SOAP interface—the URL, MD5 and size parts of a specification are specified separately, not in a single string joined with '=' .

      Submitting using form data
      Submitting a job using CURL
      curl \
          -d name=dsp \
          -d grid=NULL \
          -d args='-dpf=docking.dpf' \
          -d tag='Test job' \
          -d input[docking.dpf][url]=http://example.com/myproject/download/inputs/publicautodock423/docking.dpf \
          -d input[docking.dpf][md5]=a7bac5a941a85660cd87bf83f93b852a \
          -d input[docking.dpf][size]=2933 \
          -d input[inputs.zip][url]=http://example.com/myproject/download/inputs/publicautodock423/inputs.zip \
          -d input[inputs.zip][md5]=cbb8c0ada8e197d6db707e6ce4f03ca6 \
          -d input[inputs.zip][size]=3270896 \
          -d output[0]=log.dlg \
          http://example.com/myproject/download/wss/jobs?hdr=1 -L
      id grid alg status gridid args griddata tag creation_time metajobid userid error_info
      022a9b75-8a08-4f5d-8188-c8687659e60d NULL dsp INIT  -dpf=docking.dpf  Test job 2013-01-22 13:30:32   

      Alternatively:

      Submitting a job using CURL
      curl \
          # [ same as above ] \
          http://example.com/myproject/download/wss/jobs?redir=0
      022a9b75-8a08-4f5d-8188-c8687659e60d
      Submitting using JSON

      This is an example job description in JSON:

      example-job.json
      [
          {
              "name": "dsp",
              "grid": "NULL",
              "args": "-dpf=docking.dpf",
              "tag": "Test job",
              "input": {
                  "docking.dpf": {
                      "url": "http://example.com/myproject/download/inputs/publicautodock423/docking.dpf",
                      "md5": "a7bac5a941a85660cd87bf83f93b852a",
                      "size": 2933
                  },
                  "inputs.zip": {
                      "url": "http://example.com/myproject/download/inputs/publicautodock423/inputs.zip",
                      "md5": "cbb8c0ada8e197d6db707e6ce4f03ca6",
                      "size": 3270896
                  }
              },
              "output": [
                  "log.dlg"
              ]
          }
      ]

      This example job can be submitted with the following command.

      Submitting a JSON job
      curl \
          --header 'Content-Type: application/json' \
          --data @example-job.json \
          http://example.com/myproject/download/wss/jobs

      Admin Guide

      Follow these steps to deploy the REST interface for the Bridge:

      1. Create a directory that will be published by the project web server. For example, if you create a directory named wss in project/download, the directory will be available through http://<projecturl>/download/wss.
      2. Setup security for that directory. Create a .htaccess file in the directory, and enable overriding AuthConfig in the project's httpd.conf.
      3. Simply copy the php scripts that constitute the interface to the directory just created.

      The following is an example .htaccess file that enables the use of “pretty” URLs, and restricts access to internal network. You can setup any kind of security Apache supports.

      .htaccess
      Order deny,allow
      Deny from all
      Allow from lpds.sztaki.hu
       
      <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteBase /edgidemo/download/wss/
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule ^(.*)$ 3gb.php/$1 [L]
      </IfModule>

      Don't forget to enable overriding authorization in the project's main httpd.conf:

      [project_home]/project/[project_name].httpd.conf
      [...]
      <Directory "[project_home]/project/html/user">
         [...]
          AllowOverride AuthConfig FileInfo Limit
       
      [...]   
      manual/restif.1358858701.txt.gz · Last modified: 2013/01/22 12:45 by a.visegradi