REST API is Incomplete
The REST API does not allow direct access to all actions.
/todos.xml contains only active items. No access is available to deferred or completed items. These items can be found if you dig for them specifically by searching sequentially for todos/{number}.xml, but this is somewhat tedious.
It is undesirable to modify the existing /todos.xml as this would cause problems for existing apps.
Secondarily, todos.xml is a very heavyweight file. It contains the full content of every active todo. This is not suitable for incremental update of a synchronized database as would be appropriate for a mobile app.
Proposed solution:
Add several "index" feeds.
/todos/active.xml
/todos/deferred.xml
/todos/complete.xml
The union of these three feeds will allow REST API access to all current todos.
Each feed should contain only the ID and updated-at field for todos of the matching types.
The reduced content in these feeds will allow a client to download the full set of open todo IDs and then look at the updated-at times and pull only the specific todos which have actually changed since the last synchronization of the remote app.
Finally, it may be desirable to amend the REST API documentation slightly to document the life cycle of a todo.
Are todos IDs guaranteed to be assigned in increasing numerical order?
Are they guaranteed to be created without gaps in the sequence?
Under what conditions is a ID retired or removed from the set once it has been created?
/todos.xml contains only active items. No access is available to deferred or completed items. These items can be found if you dig for them specifically by searching sequentially for todos/{number}.xml, but this is somewhat tedious.
It is undesirable to modify the existing /todos.xml as this would cause problems for existing apps.
Secondarily, todos.xml is a very heavyweight file. It contains the full content of every active todo. This is not suitable for incremental update of a synchronized database as would be appropriate for a mobile app.
Proposed solution:
Add several "index" feeds.
/todos/active.xml
/todos/deferred.xml
/todos/complete.xml
The union of these three feeds will allow REST API access to all current todos.
Each feed should contain only the ID and updated-at field for todos of the matching types.
The reduced content in these feeds will allow a client to download the full set of open todo IDs and then look at the updated-at times and pull only the specific todos which have actually changed since the last synchronization of the remote app.
Finally, it may be desirable to amend the REST API documentation slightly to document the life cycle of a todo.
Are todos IDs guaranteed to be assigned in increasing numerical order?
Are they guaranteed to be created without gaps in the sequence?
Under what conditions is a ID retired or removed from the set once it has been created?
Leave a comment
on 2010-11-04 00:58 *
By lrbalt
Type set to enhancement
Version set to git-devel
Component changed from None to Functionality (app)
Milestone set to Someday/Maybe
Type set to enhancement
Version set to git-devel
Component changed from None to Functionality (app)
Milestone set to Someday/Maybe
These are very good ideas. Not sure about the release to do this, so I put them in someday/maybe.
Considering this further, some new thoughts come to mind. Adding new paths was a bogus idea on my part.
Instead, use the existing single URL with http query strings
todos.xml returns as current
todos.xml?state=active returns as current behavior
todos.xml?state=completed returns completed actions
todos.xml?state=deferred returns deferred actions
todos.xml?state=all returns all actions.
(are there other states?)
todos.xml?format=full returns as current
todos.xml?format=index returns brief format with ID and modification date only
all combinations of state and format should be accepted --- ie:
todos.xml?state=all&format=index returns brief format for all states
http transport header parameter 'if-modified-since' should be applied to filter results (comes with rails automatically?)
Instead, use the existing single URL with http query strings
todos.xml returns as current
todos.xml?state=active returns as current behavior
todos.xml?state=completed returns completed actions
todos.xml?state=deferred returns deferred actions
todos.xml?state=all returns all actions.
(are there other states?)
todos.xml?format=full returns as current
todos.xml?format=index returns brief format with ID and modification date only
all combinations of state and format should be accepted --- ie:
todos.xml?state=all&format=index returns brief format for all states
http transport header parameter 'if-modified-since' should be applied to filter results (comes with rails automatically?)
currently we have
todos/1.xml
todos.xml (all active todos)
tickler.xml ( --> state=deferred)
I'll add
/todos/done.xml to get all completed todos (slow!)
/todos/hidden.xml to get all hidden, active todos (note that the state is project_hidden. this will change in the future)
/todos/calendar.xml to get all due todos
todos/1.xml
todos.xml (all active todos)
tickler.xml ( --> state=deferred)
I'll add
/todos/done.xml to get all completed todos (slow!)
/todos/hidden.xml to get all hidden, active todos (note that the state is project_hidden. this will change in the future)
/todos/calendar.xml to get all due todos
(In revision:174becee81cb4f87f44ee30070ce41d50e767637) fix #1078 and document it on the REST_API page
Branch: master
Branch: master