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 can access at http://localhost:8080/proteios/app (URL)
- 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
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):
- 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". - The combined username:password string is encoded using Base64, e.g. for "
john:cow" the result is "am9objpjb3c=". - 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=". - 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=*
