ChemGPS-NP Web - Web Services API (HTTP RPC)

Introduction:

This is a lightweight protocol that uses URI encoded requests sent either to the request broker or direct to the script thru HTTP. The output (response) format is configurable on the server and can also be selected by the caller (the client). The output formats that can be selected are:

XML:XML format using a minimal set of tags.
FOA:Fast Object and Array encoding (described in the manual).
PHP:Serialized data using PHP serialize() function.
JSON:JavaScript Object Notation (JSON) data-interchange format.
WDDX:Web Distributed Data eXchange (WDDX) mechanism.

The default format is FOA.

Manual:

The full manual is available and browsable online by visiting: ws/http/docs?format=html

Examples:

An request to list all queued jobs (thru the request broker) looks like this:

http://localhost/batchelor/ws/http/queue?format=xml

Request Broker vs. Script Direct:

Listing result files thru the request broker:

http://localhost/batchelor/ws/http/readdir?result=1234&jobid=99

Listing result files thru direct access:

http://localhost/batchelor/ws/http/result.php?result=1234&jobid=99

Methods:

These methods are the called to interact with the queue:

suspend:Suspend an already running job.
resume:Resume a job thats in paused or stopped state.
enqueue:Enqueue and start new job.
dequeue:Delete an running or finished job.
queue:List queued and finished jobs.
watch:Monitor queue for finished jobs.
opendir:List result directories.
readdir:List files in a specific result directory.
fopen:Get content of an result file.
stat:Provides stat of an enqueued job.

These (meta data) methods provides info about the HTTP RPC service:

info:List all methods thats part of the API.
func:Show detailed information about a single RPC method.
docs:Show the HTTP RPC method API as manual.

These methods are for error handling:

errors:Return an collection of all defined errors (codes and messages).
errmsg:Return error message string for an given error code.

The func method can be used by a web service client to find out how to call any of the methods. Try it out by either running CLI:

bash$> cd utils
bash$> php ws.php --func=func --params='name=readdir'

  -- or HTTP: ---

http://localhost/batchelor/ws/http/func?name=readdir

See the manual for more information.

Error handling:

The HTTP status code 200 gets returned for any successful method call, that is, if everything worked out as excepted. Anything else is considered and error.

Errors are reported with these HTTP status codes:

These error code are a quick way to find out if any problem occured.

The error details are in the custom HTTP entiety X-RPC-Error: NN, where NN is an error number. The error numbers are defined in include/ws.inc, but its associated error message is accessable from the client by sending another query to:

http://localhost/batchelor/ws/http/errmsg?code=nnn

If you get anything else than HTTP status 200 and if X-RPC-Error is set, then its an method call error.

Testing:

The HTTP RPC API can be tested using the web service client utils/ws.php

Query information about the resume method:

bash$> php ws.php --type=http --func=func --params='name=resume'

Submit a new job using URL encoded indata:

bash$> php ws.php --type=http --func=enqueue --params='indata=hello'

Dito, but now using --post to submit the file simula.c as indata:

bash$> php ws.php --type=http --func=enqueue --post=simula.c

List jobs finished with wanings, sorted on jobid:

bash$> php ws.php --type=http --func=queue --params='sort=jobid&filter=warning'


Index :: Introduction :: Setup :: SOAP :: REST :: HTTP RPC :: XML-RPC