This page last changed on Mar 24, 2005 by gbevin.

REST stands for REpresentational State Transfer. It is the name given to the architectural style of the Web by Roy Fielding.

More information about it can be found here.

Overview

To interact with Bla-bla List you have to send simple HTTP GET or POST requests to the http://blablalist.com address. Each method is a simple URL that you have to append to the base address. Each argument is either provided as a query string parameter or a post request parameter. So for instance, the following method:

methodname(argument1=value1, argument2=value2)


translates to:

http://blablalist.com/methodname?argument1=value1&argument2=value2

Submissions

Bla-bla List supports the envoy of multiple consecutive actions in a single request while calling only one method. These are called submissions and each submission has its collection of dedicated parameters.

Submissions are particularly handy when methods are implicitly preceeded by other methods. We typically use this to be able to login and send method parameters in one go.

For instance, this request identifies the user and creates a new list for him:

http://blablalist.com/createlist?
    submission=credentials&
    login=johnsmith&
    password=password&
    submission=create&
    name=Things+I+need+to+do+today

Authentication

Most actions require an authenticated user account.

There are two ways to do this:

  • you log in and start an authentication session
  • you perform one-shot operations and authenticate through a submission at each request

logging in

When you log in beforehand, you'll receive a unique authentication identifier that you can later use as a token to prove that you have already authenticated. You provide this token as a value of the authid argument. For instance:

http://blablalist.com/createlist?
    authid=23eb476a7be9a9a8d84a0e166acdcbd6&
    submission=create&
    name=Other+things+that+I+need+to+do

If your client supports it, an authid cookie will also be created. In that case, you don't have to provide the argument to every method call. The cookie will be sent automatically and Bla-bla List will use it.

one-shot operations

An example of a one-shot operation can be found in the previous section about submissions.

Error reporting

When errors occur during the execution of the method and the submission, an errors tag will be added to the root tag of the response. This is an example of a possible errors tag:

<errors>
    <error>MANDATORY:firstname</error>
    <error>MANDATORY:lastname</error>
    <error>WRONGLENGTH:login</error>
    <error>NOTSAME:password2</error>
    <error>INVALID:email</error>
</errors>

Invalidity

When you try to work with data that doesn't exist (by providing a wrong id) or that you don't have access to, you simply receive the following response:

<invalid/>

Handling authentication session timeouts

If users are logged in at the beginning, and you use the authentication ID argument to authenticate them, their authentication session will time out after 20 minutes of inactivity.

When this authentication ID has expired and you try to execute a method that requires it, you're able to resume the action as if nothing happened.

For instance, this expired request:

http://blablalist.com/createlist?
    authid=23eb476a7be9a9a8d84a0e166acdcbd6&
    submission=create&
    name=Other+things+that+I+need+to+do

will not execute the action, but will return this reponse instead:

<authenticate>
    <url href="/createlist?submission=credentials&amp;submissioncontext=L..snip..u&amp;childrequest=b..snip..%3D&amp;triggerlist=&amp;inputs=Y..snip..%3D"/>
</authenticate>

You then know that the user has to log in again and the action he was doing has been serialized in the URL you received in the response. With this URL you authenticate the user if you add the login and password arguments and execute the original method, like this:

http://blablalist.com/createlist?
    submission=credentials&
    submissioncontext=L..snip..u&
    childrequest=b..snip..%3D&
    triggerlist=&
    inputs=Y..snip..%3D&
    login=johnsmith&
    password=password

If your client supports cookies, you'll receive an authid cookie with a new valid authentication session identifier and the following response, for instance:

<create authid="574f85ccb7c5e1ddd6aa911b7710c3e9">
    <success id="378"/>
</create>

In case your client doesn't support cookies, you can extract the authid from here and continue using it further on.

Supported methods

Account management

register
login
resetpassword
logout
changepassword
changeemail

List management

createlist
fetchlists
getlist
reorderlist
editlist
deletelist
addentry
toggleentry
reorderentry
maillist

Sharing

privatesharing
publicsharing
removeshared

Document generated by Confluence on Oct 19, 2010 15:04