REST — Verbs or Adverbs?

OK here I go with right-brain drift again.

The premise of the uniform interface for REST is appealing: you get 4 verbs, and you need to define your nouns in a way that leverages those 4 verbs. Without abusing POST.

So what if we defined our classes that way? What if I defined an interface with the following signatures:

public interface Restful<T>
T get(Map<String,String> query);

Object put(T o);

Object delete(Map<String,String> query);

Object post(Object input);

I could certainly write a program where all my objects used that interface. It would certainly conform directly with The Interwebs, because I’d just have to have some sort of list of what objects were visible, and my application container could support remote HTTP communication with practically nothing in between.

It would look really weird though, and I think that’s why the Java folks moved instead to annotations: @GET @POST etc. That way, they could keep their regular object-oriented syntax, but still figure out where to hang hooks for RESTful calls.

So why are we, as a herd, squeezing ourselves into the REST bottle?

Maybe the answer is that the HTTP/REST verbs should not be taken as verbs, but rather as adverbs. That is, a method that you invoke GETly has certain properties: it’s probably cacheable, it takes simple input and returns complex data, etc. In fact, we could describe the RESTful adverbs this way:


  • cacheable, with constraints
  • input is a a map of string to string
  • output is a complex (i.e. structured) object
  • output data is typed according to the class of the URI
  • safe — i.e. does not intend to alter data
  • idempotent — i.e. repeatable
  • PUT

  • sets or updates data
  • complex input data
  • no output aside from status messages
  • input data is typed according to the class of the URI
  • not cacheable
  • unsafe (data changes)
  • idempotent (repeatable)

  • removes data from the system
  • no input — just the identifier
  • no output aside from status messages
  • not cacheable
  • sort of unsafe (data changes, but its a implementation
    decision whether deleting already deleted data is results in an
    error response)
  • idempotent (repeatable)
  • POST

  • the method takes an arbitrary input object and returns an arbitrary object
  • input is a complex object (i.e structured data)
  • output is a complex object
  • input and output data types aren’t necessarily related to anything else
  • not cacheable
  • not safe
  • not idempotent

So I could have an class, where the accessors would look like

public String getName()

public String setName()

…because the getters and setters play nicely with the RESTful adverbs.

But other methods might play nice, too. For example, if you have a recalculate method that recaculates and sets a bunch of internal values in the class, that method works POST-fully

public String recalculate()

And so on. A lot of the methods in my system — but I suspect, less than we’d expect — would look like a good old-fashioned input/output, like the classic POST case.

public ThozzRegulator calibrate(CalibrationTemplate template)

In fact, if we set aside the data semantics, maybe the RESTful adverbs really classify the fundamental behavior of all methods:

safe not safe
idempotent GET PUT, DELETE
not idempotent n/a POST

We’d just need a verb that is safe but not idempotent (!??!?!?) and then we could apply an adverb to every method in our system. 😉



Filed under opinionizing, REST

3 responses to “REST — Verbs or Adverbs?

  1. Pingback: This Week in #REST – Volume 31 (Dec 13 2010 – Jan 8 2011) « This week in REST

  2. Johannes

    how can a method be safe (not altering data) but not idempotent (e.g. calling it twice gives an other state as calling it once)? Do you have an axample for this? I suspect that beeing “safe” implies idempotence.

    • roby2358

      I left that box open in case someone finds something like that. I’m with you — I don’t know how a safe / non-idempotent method would work.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s