User Tools

Site Tools


manual:restif

Link to this comparison view

manual:restif [2013/01/22 12:45]
a.visegradi
manual:restif [2013/05/13 12:16]
Line 1: Line 1:
-====== REST interface for the 3G Bridge ====== 
  
-This manual describes the use and configuration of the 3G Bridge 
-[[interface:​rest|REST interface]]. 
- 
-===== User Guide ===== 
- 
-The REST interface is an alternative to the [[interface:​soap|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 
-[[#​AdminGuide|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 
-<​file>​ 
-3G Bridge 1.9 
-</​file>​ 
-  http://​example.com/​myproject/​download/​wss/​version?​hdr=1 
-<​file>​ 
-version 
-3G Bridge 1.9 
-</​file>​ 
-  http://​example.com/​myproject/​download/​wss/​version?​format=json 
-<​file>​ 
-[{"​version":"​3G Bridge 1.9"}] 
-</​file>​ 
- 
-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=| 
-<​file>​ 
-093fd32b-4604-4c06-9ba9-d3aae7a6b80d|Cloud|cloud|CANCEL||--image=ami-00000021|||2012-09-11 11:20:06| 
-</​file>​ 
- 
-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 
-<​file>​ 
-93fd32b-4604-4c06-9ba9-d3aae7a6b80d CANCEL 2012-09-11 11:20:06 
-</​file>​ 
- 
-==== 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 === 
- 
-<​code>​http://​example.com/​myproject/​download/​wss/​version</​code>​ 
-<​file>​3G Bridge 1.9</​file>​ 
- 
-SOAP equivalent: 
-  wsclient -m version -e http://​example.com:​8091/​ 
- 
-=== Querying queues === 
- 
-== Querying available queues == 
- 
-<​code>​http://​example.com/​myproject/​download/​wss/​queues</​code>​ 
-<​file>​ 
-Cloud audiveris 1 
-edgidemo audiveris 1  
-edgidemo bwa-boinc 1 
-NULL dsp 
-MetaJob dsp 
-... 
-</​file>​ 
- 
-SOAP equivalent: --- 
- 
-== Querying available grids == 
-<​code>​http://​example.com/​myproject/​download/​wss/​grids</​code>​ 
-<​file>​ 
-Cloud 
-edgidemo 
-MetaJob 
-NULL 
-</​file>​ 
- 
-SOAP equivalent: --- 
- 
-== Querying available algorithms for a grid == 
- 
-  - All attributes: <​code>​http://​example.com/​myproject/​download/​wss/​grids/​edgidemo</​code>​ 
-  - Only algorithm names: <​code>​http://​example.com/​myproject/​download/​wss/​grids/​edgidemo/​alg</​code>​ 
- 
-<​file>​ 
-edgidemo audiveris 1  
-edgidemo bbgc 1  
-edgidemo Blender 1  
-edgidemo bwa-boinc 1 
-... 
-</​file>​ 
- 
-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 
-<​file>​ 
-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 
-... 
-</​file>​ 
- 
-SOAP equivalent: --- 
- 
-== Querying a single job == 
- 
-  http://​example.com/​myproject/​download/​wss/​jobs/​093fd32b-4604-4c06-9ba9-d3aae7a6b80d 
-<​file>​ 
-093fd32b-4604-4c06-9ba9-d3aae7a6b80d Cloud cloud CANCEL ​ --image=ami-00000021 ​  ​2012-09-11 11:20:06 
-</​file>​ 
- 
-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 
-<​file>​ 
-093fd32b-4604-4c06-9ba9-d3aae7a6b80d CANCEL 
-</​file>​ 
- 
-  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 
-<​file>​ 
-093fd32b-4604-4c06-9ba9-d3aae7a6b80d d2048dd6-464e-47c9-a4d0-373a9de25bdb_e933a6f8-7365-4b58-846d-a38be7d4ba24_76a26b38-88fd-4ba3-912b-2b1e30ed74d6 
-</​file>​ 
- 
- 
-== Querying finished jobs == 
- 
-  http://​example.com/​myproject/​download/​wss/​jobs/​finished/​id+status 
-<​file>​ 
-093fd32b-4604-4c06-9ba9-d3aae7a6b80d FINISHED 
-0bba95f9-38ea-4cf9-8125-6bc3e93af154 ERROR 
-0f25e8cb-45f6-4f7f-83b4-4525dc245b11 FINISHED 
-</​file>​ 
- 
-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 ''​POST''​ing 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 
-[[manual:​soapif|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 == 
- 
-<code bash 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 
-</​code>​ 
-<​file>​ 
-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 ​   
-</​file>​ 
- 
-Alternatively:​ 
- 
-<code bash Submitting a job using CURL> 
-curl \ 
-    # [ same as above ] \ 
-    http://​example.com/​myproject/​download/​wss/​jobs?​redir=0 
-</​code>​ 
-<​file>​ 
-022a9b75-8a08-4f5d-8188-c8687659e60d 
-</​file>​ 
- 
-== Submitting using JSON == 
- 
-This is an example job description in JSON: 
- 
-<file 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"​ 
-        ] 
-    } 
-] 
-</​file>​ 
- 
-This example job can be submitted with the following command. 
- 
-<code bash Submitting a JSON job> 
-curl \ 
-    --header '​Content-Type:​ application/​json'​ \ 
-    --data @example-job.json \ 
-    http://​example.com/​myproject/​download/​wss/​jobs 
-</​code>​ 
- 
-===== Admin Guide ===== 
- 
-Follow these steps to deploy the REST interface for the Bridge: 
- 
-  - 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%%''​. 
-  - Setup **security** for that directory. Create a ''​.htaccess''​ file in the directory, and enable overriding ''​AuthConfig''​ in the project'​s ''​httpd.conf''​. 
-  - 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. 
- 
-<file apache .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>​ 
-</​file>​ 
- 
-Don't forget to enable overriding authorization in the project'​s main 
-''​httpd.conf'':​ 
- 
-<file apache [project_home]/​project/​[project_name].httpd.conf>​ 
-[...] 
-<​Directory "​[project_home]/​project/​html/​user">​ 
-   [...] 
-    AllowOverride AuthConfig FileInfo Limit 
- 
-[...]    
-</​file>​ 
manual/restif.txt · Last modified: 2013/05/13 12:16 (external edit)