REST: 'There aren't enough verbs'

I think one of the more frequent issues that people have when starting to work with a RESTful architecture is that "there aren't enough verbs".

Why having few verbs is good

When we look at the big picture we see that this paucity of verbs is in fact one of the strengths of REST. A small, standard set of verbs allows all parties to agree (in the most part) on what the semantics of those verbs are. This in turn allows the creation of a lot of loosely coupled infrastructure which any REST system can take advantage of. An obvious example is the sophisticated caching system within the world wide web. All parties can agree on what a GET means, specifically that it's an idempotent operation. That allows intermediaries to know when a response is cachable. If each application was creating its own set of verbs we'd no longer be able to leverage all this 'free' infrastructure which has built up. If a cache somewhere between your user's browser and your data center doesn't understand what the semantics of some custom verb are then it can't safely cache your responses. Same goes for your user's browser. This is one of the reasons why RESTful folks don't like web services with RPC-style architectures. By tunnelling everything through POST and a single URI these services lose the ability to confer semantics to intermediaries. These kinds of services are on the web, but not of the web.

What to do when you 'need' more verbs

So, we are agreed that a small, standard set of verbs is a good thing. What then is an API designer to do when modeling a complex operation which doesn't map nicely onto that small set? In my experience there are generally two solutions. We can use an overloaded POST, or we can add some additional 'activity resources' to the resource space of the API. I tend to prefer the latter, but I think it's important to not be dogmatic about this. There are certainly situations where an overloaded POST is the way to go.

Let's discuss what I mean by 'activity resources'. Generally when people start designing the resource space for their RESTful API they might write a description of what functionality the API seeks to expose, and then go through the text underlining nouns. If this is reminding you of an analysis technique for a certain other paradigm then stick with me, I'll be coming back to that in the next section. This set of nouns would generally be a good starting point for identifying resources. I'll call these types of resources Entity Resources. Let's say we're working on a hotel reservation system. After this initial stage of analysis we might come up with a set of entity resources such as Guest, Room, Hotel, Bill, etc. We'd probably also have Reservation in there too, but I wouldn't classify that one as an entity. So far so good. Now, let's say we're working on the checkout part of the system, in particular on credit card processing. We need a way to represent the act of a Guest paying their Bill with a credit card, having that credit card transaction approved or declined, etc. A lot of developers (particularly those coming from an RPC mindset) will want to do something like add a PAY verb to the Bill resource. This makes sense. Paying is an action that is applied to the Bill. It makes sense, but as we've discussed above REST frowns upon extending our small set of verbs. So instead we can create an Activity Resource called Payment. This resource can contain a reference (in the form of a uri) to the Bill it is a Payment for, along with details like credit card number, etc. In addition we can add a Payments resource which belongs to each Bill. When a customer wants to pay a bill they can send a POST to the Payments resource, supplying a representation of the payment they want to make. That POST will create a Payment resource representing the transaction, and supply the user with a uri for that resource in the form of a redirect. The customer can GET on that resource to check on the state of the payment transaction (Processing,Successful,Denied), etc. Maybe if the payment was denied they could PUT to the resource with a corrected credit card number. The key pattern here was to take an action (paying a bill), and to model that as a transitory Activity resource. Adding that extra level allows us to model the behavior in a RESTful way. I've frequently seen transactions modeled RESTfully in this way.

Sidebar: Parallels in grokking REST and grokking OO

When I was going through the slow, laborious process of getting these ideas into my thick skull I experienced a vague feeling of déjà vu. I eventually realized that this was just like when I first started to really grok object-oriented design. Often when students are being taught to design object oriented systems a suggested technique is to write a description of the business domain and then underline the nouns in the description. These nouns will be the classes in your system. However, after gaining experience with OO I think most developers realize that these classes are not where the meat of a design lies. The meat lies in the interaction between these entities, how they are composed and how they interact. Using polymorphism and composition to create clean, loosely-coupled systems becomes much more interesting than designing the Is-A inheritance heirarchies that often appear in introductions to OO. And here lies the parallel with learning RESTful design, and my sense of déjà vu. When learning REST the core concepts of Resources, Actions, Uris, etc. are necessarily explained first, and most pedagogical examples focus on simple systems consisting of what I referred to above as Entity Resources. However when you start to do real work with a RESTful architecture you start realizing that large parts of the system are about modeling the relations and interactions between these Entity Resources. I expect that as we gain more experience with the REST style then the common problems and shared solutions will start to emerge, in the same way as we saw OO design mature in the 80s and 90s.

mock.willExecute(...) in mock4as

As I mentioned in a previous post I've recently been adding some features to mock4as, a mocking library for ActionScript. In this post I'm going to talk about the new mock.willExecute(...) feature which I recently implemented.

Perhaps the easiest way to describe willExecute is as a dynamic version of willReturn, so before we dive into willExecute I should briefly explain willReturn. willReturn allows a user to specify what value a mocked out method should return when called. An example should shed some light:

var mock:MockInterface = new MockInterface();
mock.expects('lookupBookTitleByISBN').withAnyArgs().willReturn('War and Peace');
assertEquals( 'War and Peace', mock.lookupBookTitleByISBN() );

You can see that when we call the method mock.lookupBookTitleByISBN() it returns 'War and Peace', because that's what we specified in our expectation. This is a fundamental feature that I would expect any mocking system to supply. It's the primary tool for controlling the indirect inputs into the system that your testing. That said, newcomers to mocking do sometimes get confused with this feature and think that willReturn is specifying what you expect the method to return. That's not what we're doing here, we're instructing the mock what to return. We're providing indirect input, not testing indirect output (the other main purpose of mocking). I suspect that adding a new method to mock4as which is similar mock.expects(...) but intended for use in cases where you just mocking the method to control indirect input would be helpful. Something like mock.ifCalled('foo').willReturn(someResult) might clear up some of the confusion between specifying an expectation that a method is called and injecting a return value for a method.

Anyway, back to the subject at hand. The willExecute feature takes the concept of willReturn and makes it dynamic. Rather than specifying a hard-coded value to be returned whenever the method is called you instead supply an arbitrary function which will be executed whenever the specified method on the mock is called. For example:

var mock:MockInterface = new MockInterface();
mock.expects('lookupBookTitleByISBN').willExecute(
  function( isbn:String ):String{
    return "Title for isbn " + isbn;
  } );

assertEquals( 'Title for isbn ABC', mock.lookupBookTitleByISBN('ABC') );
assertEquals( 'Title for isbn XYZ', mock.lookupBookTitleByISBN('XYZ') );

Every time lookupBookTitleByISBN(...) is called the mocking system looks up and executes the attached function, passing in the arguments supplied to lookupBookTitleByISBN(...). In addition it returns whatever value was returned by the attached function. Note from our example that this allows output to vary with the input, because we have supplied a function rather than a static value.

The real fun starts when we realize that functions in actionscript can act as closures. This leads to a lot of interesting ways to use willExecute. To give one (rather contrived) example, we can use willExecute to specify some quite sophisticated ordering constraints:

public function test_accountsAreSubmittedInAscendingNumericalOrder():void {
  var mock:MockInterface = new MockInterface();

  var lastAccountId:int = -1;
  mock.expects('submitAccount').withAnyArgs().willExecute(
    function(account:account):void {
      assertTrue( account.id() >= lastAccountId );
      lastAccountId = account.id();
    }
  );

  exerciseSystemUnderTestUsing( mock );
}

Note here that we have used variables outside of the closure's local scope to maintain state across calls to the mocked method. Also note that we can call methods like assertTrue(...) from inside the attached function.

Some other potential uses of this feature include:

Verifying arguments passed to a method where the argument is complex: Let's say a method takes a Parameter Object which is an instance of a class with 10 properties, but we're only interested in three:

public function testXYZCoordinatesAreAllSetToZero():void
{
  var mock:MockSomeInterface = new MockSomeInterface();

  mock.expects('methodWithScaryParams').withAnyArgs().willExecute(
    function(bigObject:ComplexParameterObject):void{
      assertEquals( 0, bigObject.coordX );
      assertEquals( 0, bigObject.coordY );
      assertEquals( 0, bigObject.coordZ );
    }
  );

  exerciseSystemUnderTestUsing(mock);
}

Verifying arguments passed to a method with a lot of parameters but where we're only interested in some of the arguments:

public function testNameAndAddressAreNotEmpty():void
{
  var mock:MockSomeInterface = new MockSomeInterface();

  mock.expects('methodWithManyParams').withAnyArgs().willExecute(
    function(boring:String,uninteresting:XML,name:String,address:String,dontCare:Function):void{
      assertNotEquals( "", name );
      assertNotEquals( "", address );
    }
  );

  exerciseSystemUnderTestUsing(mock);
}

Verifying some internal characteristics of an argument:

public function testNameAndAddressAreNotEmpty():void
{
  var mock:MockSomeInterface = new MockSomeInterface();

  mock.expects('someMethod').withAnyArgs().willExecute(
     function(lotsOfXml:XML):void{
      assertEquals( "Dave", lotsOfXml.body.person.firstName );
      assertEquals( "Thomas", lotsOfXml.body.person.lastName );
    }
  );

  exerciseSystemUnderTestUsing(mock);
}

It's interesting to note that willExecute can be used to accomplish two goals. You can use it to control the Indirect Input into the system you're testing (which is what willReturn is also used for, as I touched on above). In addition you can also use it to test the Indirect Outputs of your system. This is what's happening above when assertEquals(...), assertTrue(...) and the like are called from within the attached functions. My personal experience is that something like willExecute tends to be used more often as an ad hoc way of testing Indirect Output than as a way of supplying Indirect Input (which can most time be handled adequately using willReturn). Most of the time I use it to express non-trivial expectations on the input to a method. In a lot of frameworks the need to do this is reduced by the presence of custom argument matchers. These allow you to capture complex expectations on a method's input parameters by implementing classes which you then provide to your mock during the expection setting phase. For examples from other mocking frameworks you could look at jMock and Mockito.

Finally, you may remember I started off describing willExecute above is as a dynamic version of willReturn. In fact, willReturn could be trivially implemented using willExecute:

public function willReturn(object:Object):void{
  willExecute( function():Object{ return object; } );
}

The same is true of the willThrow() feature (which allows a user to ask a mock to throw a specific exception when a method is called).

public function willThrow(error:Error):void{
  willExecute( function():void{ throw error; } );
}

fun with Symbol#to_proc

As I start to get fluent in ruby I often find myself using a more functional programming style, particularly when dealing with collections. That generally leads to lots of little block-centric operations. I recently discovered a really elegant trick to make that code a little nicer.

Let's say there's a Person class:

class Person
    attr_accessor :first_name, :last_name, :age
end

and I have a collection of people which I'd like to sort by age. An obvious approach would be:

people.sort_by{ |person| person.age }

That works, but it is a little wordy. This is ruby, after all! Wouldn't it be nice if we could write this instead:

people.sort_by &:age

Isn't that neat? The magic that makes this work is this little monkey patch to the Symbol class.

class Symbol
  def to_proc
    Proc.new { |*args| args.shift.__send__(self, *args) }
  end
end

Note that this is already done for you in Rails and in Facets - in fact that's where I lifted this code from.

So how does this work? When we called sort_by we passed in the :age symbol, but we used the & to indicate that it should be treated as a block. When you supply a method with a block which isn't a Proc instance ruby helpfully attempts to coerce it into a Proc by calling to_proc. Because of the Symbol monkey patch to_proc now returns a block which will invoke a method with the same name as the symbol itself on whatever object it is passed in. Phew. Re-read that last sentence 5 times. The end result is that the following two blocks are identical:

block_a = :some_method.to_proc
block_b = proc { |x| x.some_method }

It follows that the following two operations are identical:

people.sort_by{ |person| person.age }
people.sort_by &:age

Voila! I should point out here that I'm not exactly the first person to discuss this great trick. See for messirs Thomas and Williams.

In fact, it's such a common idiom that it will apparently be baked right into ruby 1.9.