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

• 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.

List My Projects (GET)

Open your favourite browser and type the following in the URL

http://localhost:8080/proteios/resource/projects?username=john&password=cow

You should see a tabdelimited result similar to

 Id
 2
 3

I have entered two projects using the web client and those are their ids. The service result format is tab delimited with the first row being the header. Now this doesn't tell you much. You probably want to know the project names as well. When sending a GET message to the service we have tried to use the SQL syntax for query parameters so if you want to query for the Id and Name for all your projects write the following in the browser URL

http://localhost:8080/proteios/resource/projects?username=john&password=cow&select=Id&select=Name

You should now see

Id      Name
2       Little piggy project
3       Big cow project

Looks nice. How about listing all available properties for all my projects. Just enter select=* like this

http://localhost:8080/proteios/resource/projects?username=john&password=cow&select=*

Advanced GET requests

It's also posibble to query for data using SQL statemets such as where, order by and limit. Here's an example showing how to list all projects containing the word project and ordering them by descending Id

http://localhost:8080/proteios/resource/projects?username=john&password=cow&select=*&whereName==%25project&orderById=desc

As you can see wildcards are possible. The wildcard token is '%' and it must be escaped when written in the URL thus becomming '%25'.

Creating Samples (PUT)

As I mentioned above you cannot use your browser to send PUT requests to a server, the following examples are using curl. Let's say you want to create ten samples named sample-XX where XX is a number from 01-10. The format for uploading information is also tab separated so I'll start of by issuing a GET request to the server getting a template file for the samples. And I will also like to share the samples to my first project Little piggy project with the id 2.

Getting the file with curl will look like this in (*nix) environments

curl "http://localhost:8080/proteios/resource/projects/2/samples?username=john&password=cow&select=Name&select=ExternalId&select=OriginalQuantity" -o samples.txt

Open the file samples.txt and enter the sample names, one on each row like this

ExternalId      Name    OriginalQuantity
a1      sample-01       100
a2      sample-02       100
a3      sample-03       100
a4      sample-04       100
a5      sample-05       100
a6      sample-06       100
a7      sample-07       100
a8      sample-08       100
a9      sample-09       100
a10     sample-10       100

Now uploading the file to the same context as we got the template from will create one sample for each row and share that sample to our project. Issuing a PUT request looks like this

curl -T samples.txt "http://localhost:8080/proteios/resource/projects/2/samples?username=john&password=cow"

If you do not want to share the samples to any project it's only a matter of uploading them to the samples context like this

curl -T samples.txt "http://localhost:8080/proteios/resource/samples?username=john&password=cow"

Changing Samples (POST)

Using the POST method it's possoble to change the attribute of one specific item. To change the name of sample with id 1 issue the following command

curl -d "username=john&password=cow&Name=newname" http://localhost:8080/proteios/resource/samples/1

Deleting Samples (DELETE)

You remove a sample by sending a DELETE method specifying the URI of the sample. With curl you do it like this

curl -X DELETE "http://localhost:8080/proteios/resource/samples/2?username=john&password=cow"

which would set the removed flag on sample with id 2.