API

Build cool stuff that works with Remember The Milk.

menu

Timelines

Timelines enable the Remember The Milk API to allow certain actions to be undone. The Remember The Milk web application requests a new timeline every time the application is visited — it is up to the API user to determine how often to request a new timeline. Timelines do not expire, but they must always be used.

Timelines can be thought of as long-running database transactions within which individual sub-transactions (API method calls) can be reverted. The start of a timeline is a snapshot of the state of a users' contacts, groups, lists and tasks at that point in time. Method calls can be reverted continouously until the start of the timeline is reached.

Most contact, group, list and task methods require a timeline. New timelines can be obtained by calling the rtm.timelines.create method.

If successful, the contact, group, list and task methods return a <transaction> element. The id attribute of this element points to a transaction within the timeline passed to the called method. If the called method is revertable, an undoable attribute is set on the <transaction> element with a value of 1.

A call to rtm.transactions.undo with a transaction_id that is undoable will revert a contact, group, list or task to its state prior the method call being reverted.

Example

After authentication and getting a valid token, we ask for a timeline (rtm.timelines.create):


<rsp stat="ok">
  <timeline>744432</timeline>
</rsp>

We then use this timeline value to call rtm.tasks.setPriority to change the priority of a task from 2 to 1.


<rsp stat="ok">
  <transaction id="448653398" undoable="1"/>
  <list id="387546">
    <taskseries id="650390" created="2015-05-08T11:33:22Z" modified="2015-05-08T11:34:28Z"
               name="Demonstrate Timelines" source="api">
      <tags/>
      <participants/>
      <notes/>
      <task id="815255" due="" has_due_time="0" added="2015-05-08T11:33:22Z"
           completed="" deleted="" priority="1" postponed="0" estimate=""/>
    </taskseries>
  </list>
</rsp>

We now have our undoable <transaction> element. We decide that we want to revert the task's priority back to what it was (2) – so we call rtm.transactions.undo with a transaction_id of 448653398.


<rsp stat="ok"/>

We then check the state of our task by calling rtm.tasks.getList...


<rsp stat="ok">
  <tasks>
    <list id="387546">
      <taskseries id="650390" created="2015-05-08T11:33:22Z" modified="2015-05-08T11:37:18Z"
                 name="Demonstrate Timelines" source="api">
        <tags/>
        <participants/>
        <notes/>
        <task id="815255" due="" has_due_time="0" added="2015-05-08T11:33:22Z"
             completed="" deleted="" priority="2" postponed="0" estimate=""/>
      </taskseries>
    </list>
  </tasks>
</rsp>

And we note that the task now has its old priority of 2.