Reordering items in a RESTful way

Question

I have a table that has the following data:

id position name
== ======== =========
1     4      Fred
2     2      Wilma
3     1      Pebbles
4     5      Barney
         


        

Answer 1

What is the proper RESTful way to do this?

The idea is that your API is a disguise your domain model wears so that it can pretend to be a boring store of web documents.

When possible, you want the URI for the modification to match the URI for the GET, because you can then use generic components to manage cache invalidation at the client.

So if you read the list of users with a request like

GET /flintstones

Then you want to be using one or more of the following ideas to modify the representation

POST  /flintstones
PUT   /flintstones
PATCH /flintstones

For a PUT request, the representation in the body might just be the reordered list:

Pebbles
Fred
Wilma
Betty
Barney

and then its up to your implementation to figure out how to take that document and express it as a sequence of SQL calls.

But don't you end up with less efficiency in bandwidth and less efficiency in database queries?

For small edits to large documents, PUT may not be your best choice. You could instead take the same information that you had been putting into the URL, embed it into a patch document, and then use PATCH or POST instead.

So it could be a web form -- we're going to use application/x-www-form-urlencode data to communicate the form entries back to the server so that it can figure out what to do. Or (for cases where you are exchanging json representations, we could write out a JSON Patch document that descibes the change).