wiki:Webservice

Webservice

As proteios develops the webservice interface will allow access to more data and in more elaborate ways. I'll give a couple examples of it's use below. I'll assume the following :

  • You have installed and created a user named john with the password cow
  • User john has entered some information to proteios such as projects, samples and hit reports.

General Usage

Our webservice follows the REST design which means it's stateless and relies on the HTTP protocol for communication. Basically the webservice will support, and does to some extent already, four of the most used methods GET, POST, DELETE and PUT. Using your favourite browser you can access GET and POST methods the other two are not implemented in most browsers today. Though there are free clients out there that you can use to send PUT and DELETE messages such as Curl. Here are some examples of how to use the service.

Examples

  • Get - Used to list data
  • Put - Used to add new data
  • Post - Used to modify existing data
  • Delete

FAQ

How do I download a file?

URL/files/FILE_ID?username=NAME&password=PASSWORD

How do I show all attributes of e.g. Samples?

URL/samples?username=NAME&password=PASSWORD&select=*&limit=1

Can I filter on every attribute?

No, currently filtering is allowed on non linked columns, e.g. strings and integer values.

How do I impersonate another user

If you have the proper permissions you can impersonate another user with the 'impersonate' parameter e.g.

...?username=NAME&password=PASSWORD&impersonate=USERNAME

where USERNAME is the login name of the user you want to impersonate.

Test

There are a growing number of automated tests in client/servlet/test/src/webservice. To run all tests you can simply run

cd client/servlet/test/src/webservice
./run.sh all

Unless you specify the -v option, tests are run quietly. Errors however are written to STDERR.

Basic Authentication (Proteios SE 2.18.0 and later)

Background

Basic authentication is an HTTP method for sending username and password to a web application as an "Authorization" header (all this happens behind the scenes, invisible to the user):

  1. Username and password are combined into a string, separated by a colon; e.g. for username "john" and password "cow", the string would be "john:cow".
  2. The combined username:password string is encoded using Base64, e.g. for "john:cow" the result is "am9objpjb3c=".
  3. The Base64-encoded string is prefixed by the authorization method name and a space, i.e. "Basic ", and sent as the HTTP "Authorization" header, e.g. for "john:cow" the string "Basic am9objpjb3c=".
  4. Some web clients, e.g. FireFox 15.0.1, only send the basic authentication header if the web service responds to a first request with an error response with status 401 (HttpServletResponse.SC_UNAUTHORIZED).

If username and password are given explicitly in the URL, the convention for basic authentication is to insert "USERNAME:PASSWORD@" between the method (normally http:// or https://) and the base URL, e.g. for original URL "http://localhost:8080/proteios/", username="john", and password="cow", the URL would be http://john:cow@localhost:8080/proteios/.

It should be emphasized that basic authentication is not safer than sending username and password as parameters, as the HTTP header can be intercepted and the Base64-encoded string decoded. If security is essential, a secure connection should be used in both cases, e.g. https or other method implementing SSL/TLS.

Examples

To show all attributes of Samples using basic authentication for URL http://localhost:8080/proteios/resource/, use

http://john:cow@localhost:8080/proteios/resource/samples?select=*

If used in the URL address bar of a web browser like FireFox, you must explicitly include "http://" at the beginning of the URL.

If a URL without username and password is used in a web browser like FireFox, the latter will show a log-in pop-up dialog, where you can enter the credentials.

http://localhost:8080/proteios/resource/samples?select=*

Last modified 4 years ago Last modified on Nov 23, 2012, 8:56:45 AM