Design a REST resource to manage a list

Question

Let's say I want to design a REST store used to manage a list. A list entry would look something like this:

<listentry>
    <position>0</position>                <!-- position in the list -->
    <data>interesting information</data>  <!-- entry data -->
</listentry>

I would design the resource like this:

GET    /list/           // returns all list entries
GET    /list/{position} // returns the list entry at {position}
DELETE /list/{position} // delete list entry at {position}

PUT    /list/first      // update first list entry
PUT    /list/last       // update last list entry
PUT    /list/{position} // update entry at {position}

POST   /list/last       // inserts a new list entry at last position
POST   /list/first      // inserts a new list entry at first position

POST   /list/{position} // inserts a new list entry at {position} and moves all 
                        // entries down  the list starting from the entry that
                        // was at {position} before the insertion.

is this a legal REST resource? If not is there a way to design a rest resource so that it can manage a list?

EDIT

Thank you for the input it definetly helped. I agree with nategood and darrel that the use of first and last as special identifiers is perfectly legal (see also my question on this). Of course I could do without those magic identifiers as suggested by Saintedlama, but this would rob me of the possibillity to use them in the post requests I want to present you now.

While thinking again about the design, I would like to add two additional functionalities to my resource design suggestion.

POST   /list/{position1}/swap/{position2}   // swap the position of two elements
POST   /list/{position1}/move/{position2}   // move the element at {position1} to
                                            // {position2} and move all entries 
                                            // down the list starting from the 
                                            // entry that was at {position2}

//possible uses
POST   /list/first/swap/last                // swap first with last element
POST   /list/42/swap/2                      // swap element 42 with element 2
POST   /list/first/move/42                  // move first element to position 42
// you get the idea ...

What do you think?

Answer 1

Your resource design is perfectly OK for my REST understanding. You could improve your design by taking away the first and last magic index functionality by introducing a simple rule: If no position is provided the last item is update or the item is inserted at the last position. If you introduce this rule you don't need first and last any more. First is only a magic string representing index 0, last is obsolete due to the rule above.

As stated by @miku your items could be a resource of their own. If you plan a more generic resource list design where you need different resource types managed in one list (for example a list could manage tasks, meetings, appointments) the list items could be again references (using a resource url) to the item resource. With this referencing approach you completely decouple the list keeping functionality from the list item representation.

Edit:

This question is getting a moving target :)

You could model all position related operations as resource and operations as sub resources that you create, somehow like this:

POST   /list/positions/swap/0/2   // swap the position of two elements
POST   /list/positions/move/1/0   // move the element at 1 to 0

This positions resource could return a (HTTP) status if the operation succeeded or not, a handle to the "operation" resource (via location header) where you could check the status of the operation in case you want to move, swap asynchronous, return resources that give you some kind of log of all list position operations.

The idea to model the positions as resource is stolen from the book RESTful Web Services, where the author models a transfer transaction between two bank accounts as resource.

Answer 2

Just a few thoughts:

• URLs like .../first or .../last are kind of rpc-ish

• a list item seems to be a resource of its own, so it eventually should be addressed as one, e.g.:

  GET /list/3/item/2
  

• REST isn't easy and it takes time to wrap one's head around nested resources and the like.