Using the web service

This section covers the use of the web service by an end user. Here the ‘ModFoo’ example web service is used, which is defined by the configuration file to be deployed at https://modbase.compbio.ucsf.edu/modfoo.

Web interface

End users can simply use the web service by pointing their web browsers to https://modbase.compbio.ucsf.edu/modfoo/. This will display the index page, from where they can submit jobs or navigate to other pages.

User authentication

The web framework ties in automatically to Ursula’s login page for web service accounts. If a user logs in, his or her email address is automatically supplied to forms that ask for it; job results pages are linked from the queue page; and, potentially, data files can be passed between multiple lab web services. Unauthenticated (anonymous) users can still use lab web services, however, unless the service is experimental or very expensive in terms of computer time.

Automated use

The web framework automatically sets up each web service to allow automation. This allows a program to submit jobs, check for completion, and finally to obtain the generated results. This is achieved with a REST-style interface that talks a simple form of XML. This interface is provided by the ‘/job’ endpoint; for the fictional ModFoo web service this would be found at https://modbase.compbio.ucsf.edu/modfoo/job. XML output is requested by setting the HTTP Accept header to application/xml. Jobs can be submitted by sending an HTTP POST request to this URL containing the same form data that would be sent to the regular submit page. On successful submission, the returned XML file will contain a URL pointing to the job results. This URL can be queried by an HTTP GET to see if the job has finished (again with an Accept header). If it has, a list of URLs for job results files is returned; if it has not, an HTTP error is returned and the request can be retried later. Finally, the job results files can be downloaded using the provided URLs.

There is a simple Python interface to all Sali Lab services that use the framework, available on all Sali lab machines, that takes care of XML parsing and error handling for you. It can be used to submit jobs and collect results either from the command line or from other Python scripts. For example, to run a job on the fictional ModFoo service and wait for results, you can run from the command line on a lab machine something like:

module load web_service

web_service.py run https://modbase.compbio.ucsf.edu/modfoo/job \
                   input_pdb=@input.pdb job_name=testjob

Use web_service.py help for full details on using this utility.

Alternatively, you can do the same thing from Python with a script like:

#!/usr/bin/python

from saliweb import web_service

results = web_service.run_job('https://modbase.compbio.ucsf.edu/modfoo/job',
                              ['input_pdb=@input.pdb', 'job_name=testjob'])

(Note that you can also submit jobs to a web service from another one using the SaliWebServiceRunner class.)

Although /usr/bin/web_service.py is only installed on Sali lab machines, you can download a copy and run it on any machine that has network access and has Python and curl installed.