| | |
| | |
| | REST stands for REpresentational State Transfer. It is the name given to the architectural style of the Web by [Roy Fielding|http://rest.blueoxen.net/cgi-bin/wiki.pl?RoyFielding]. |
| | |
| | More information about it can be found [here|http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage]. |
| | |
| | h2. 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:\\ |
| | \\ |
| | {noformat} |
| | methodname(argument1=value1, argument2=value2) |
| | {noformat} |
| | \\ |
| | translates to:\\ |
| | \\ |
| | {noformat} |
| | http://blablalist.com/methodname?argument1=value1&argument2=value2 |
| | {noformat} |
| | |
| | h2. 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: |
| | |
| | {noformat} |
| | http://blablalist.com/createlist? |
| | submission=credentials& |
| | login=johnsmith& |
| | password=password& |
| | submission=create& |
| | name=Things+I+need+to+do+today |
| | {noformat} |
| | |
| | h2. 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 |
| | |
| | h4. 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: |
| | |
| | {noformat} |
| | http://blablalist.com/createlist? |
| | authid=23eb476a7be9a9a8d84a0e166acdcbd6& |
| | submission=create& |
| | name=Other+things+that+I+need+to+do |
| | {noformat} |
| | |
| | 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. |
| | |
| | h4. one-shot operations |
| | An example of a one-shot operation can be found in the previous section about submissions. |
| | |
| | h2. 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: |
| | |
| | {code:xml} |
| | <errors> |
| | <error>MANDATORY:firstname</error> |
| | <error>MANDATORY:lastname</error> |
| | <error>WRONGLENGTH:login</error> |
| | <error>NOTSAME:password2</error> |
| | <error>INVALID:email</error> |
| | </errors> |
| | {code} |
| | |
| | h2. 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: |
| | |
| | {code:xml} |
| | <invalid/> |
| | {code} |
| | |
| | h2. 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: |
| | |
| | {noformat} |
| | http://blablalist.com/createlist? |
| | authid=23eb476a7be9a9a8d84a0e166acdcbd6& |
| | submission=create& |
| | name=Other+things+that+I+need+to+do |
| | {noformat} |
| | |
| | will not execute the action, but will return this reponse instead: |
| | |
| | {code:xml} |
| | <authenticate> |
| | <url href="/createlist?submission=credentials&submissioncontext=L..snip..u&childrequest=b..snip..%3D&triggerlist=&inputs=Y..snip..%3D"/> |
| | </authenticate> |
| | {code} |
| | |
| | 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: |
| | |
| | {noformat} |
| | http://blablalist.com/createlist? |
| | submission=credentials& |
| |  | submissioncontext=LmN...snip...W9u& |
| | |
| | | submissioncontext=L..snip..u& |
| | |
| | triggerlist=& |
 | | inputs=YXV...snip...kNg%3D%3D& |
| | | inputs=Y..snip..%3D& |
| | login=johnsmith& |
| | password=password |
| | {noformat} |
| | |
| | If your client supports cookies, you'll receive an {{authid}} cookie with a new valid authentication session identifier and the following response, for instance: |
| | {code:xml} |
| | <create authid="574f85ccb7c5e1ddd6aa911b7710c3e9"> |
| | <success id="378"/> |
| | </create> |
| | {code} |
| | |
| | In case your client doesn't support cookies, you can extract the {{authid}} from here and continue using it further on. |
| | |
| | h2. Supported methods |
| | |
| | h3. Account management |
| | |
| | *[register]* |
| | *[login]* |
| | *[resetpassword]* |
| | *[logout]* |
| | *[changepassword]* |
| | *[changeemail]* |
| | |
| | h3. List management |
| | |
| | *[createlist]* |
| | *[fetchlists]* |
| | *[getlist]* |
| | *[reorderlist]* |
| | *[editlist]* |
| | *[deletelist]* |
| | *[addentry]* |
| | *[toggleentry]* |
| | *[reorderentry]* |
| | *[maillist]* |
| | |
| | h3. Sharing |
| | |
| | *[privatesharing]* |
| | *[publicsharing]* |
| | *[removeshared]* |
