Do you really know why you prefer REST over RPC?

> If a user want to stop using your service, you’ll do this (not so obvious) call:

> DELETE /users/1234

No! It would be

  DELETE /sessions/12345

or possibly

  DELETE /users/1234/session

or even

  DELETE /users/1234/sessions/3

in the case a user can have more than one concurrent different sessions (this is actually a fairly common case for the application we do were I work. We don't use http for this though).

Unless you actually want to permanently stop the user from using the system, in which case

  DELETE /users/1234

would be the perfectly obvious choice.

I like how when building REST API servers and clients there are standard components that just works. The entire API in the same format means it is easy to write a DSL across the entire API configure each endpoint - such as row level and field level permissions, pagination, filtering. If you have a well designed RPC you have the same benefit, but except with REST - you can reuse someone else's work because the design is the same. It literally takes 20 seconds to change the /user/ endpoint so:

1. Non-authenticated users can create users, and see a list of users with details that are public.

2. Authenticated users can view their own public and private details and have read/write access to most fields except is_staff.

3. Staff users have full permissions for users that belong to the country they are managing.

4. Superusers have access to everything.

Without the benefit of DSLs this would take hours to write all the if/else statements and unit test them. It would be a nightmare to do the same for all your endpoints. I assume you can write some abstraction functions to use for all your RPC endpoints but it'd be easier to reuse a library from past projects that had the same REST API design.

Example:

Row level:

    permission_classes = [
        Or(And(Or(IsOwner('id'), IsStaff), IsUpdateOnly),
            And(AllowAny, IsReadOnly),
            And(AllowAny, IsCreateOnly))]

Field level:

    is_public = And(IsActive, Is('is_public', True))
    fields = {
        'display_name': [],
        ('is_active', 'password', 'email'): [
            Or(is_staff_or_owner, IsCreateOnly)
        ],
        ('full_name', 'slug',): [
            Or(is_staff_or_owner, is_public, IsCreateOnly)
        ]
    }

I really like REST most of the time, but I do have some complaints about Rails' implementation of it. I wrote about them a few years ago:

http://illuminatedcomputing.com/posts/2011/07/restless-doubt...

Basically, after form submit errors your location bar still says /widgets or /widgets/1 rather than /widgets/new or /widgets/1/edit, so bookmarking that page, or "like"ing it, or Ctrl-L + ing are all broken. I'd much prefer a redirect back to the correct URL.

Also the distinction between "create" and "update" can break the back button, if the user creates something, then clicks back to edit their submission (because submitting a second time will create a second thing, not update their original thing). That's not Rails so much as REST in general.

I might be behind on state of the art these days...but my current api has no GET requests, everything is a POST. So in that term, we are not restful.

We had a couple of problems with GET requests: all of our data ended up in the url (we have too much info that has to be passed, we stopped working on some browsers), and the data returned could be cached (which is a HUGE problem for us).

Now, POSTs can also be cached, but there are easy ways around it...you can do the same thing with a GET, but that means adding more information to the url.

Anyway, one we got to the point of forgoing all GET requests, we ended up just doing everything with a POST for simplicity.

I generally use a pattern like:

GET /api/resource

POST /api/resource/action

Where 'action' is something a bit more descriptive than 'PUT' or 'DELETE' or whatever. Kind of like an object-oriented api... I'm still always dealing with resources, but I have custom actions for specific use cases.