Going beyond CRUD in RESTful services

Question

I am working on a WCF RESTful service and noticed that on some places I can represent non-CRUD operations (not resources) in more than one way.

Say we purchased a new TV and connected it to our private network. Now we want to build a Web Service in order to view and control the TV.

• For reading and updating the TV's properties we will use the following URI:

  http://domain/tv/ GET | PUT - getting and updating tv properties. (company, owner, inches)

• For consuming video we will use the following URI:

  ws://domain/tv/video - (assume WebSocket is the best option for video content transfer)

• And operations:

  • updateVersion
  • startBIT (Built-in self-test)
  • changeChannel
  • turnVolumeUp, turnVolumeDown

First design is to use properties for representing operations. Server will notice property changes and then perform the desired operations. Finally POSTing the operations which can't be represented by properties:

http://domain/tv/ GET | PUT - getting or setting volume or channel using a json objects.

and for updateVersion or startBIT:

http://domain/tv/ POST with {function: 'updateVersion'} or {function: 'startBIT'}

Second design is to represent all operations using a Command resource:

http://domain/tv/commands POST with {command: 'BIT', sender: 'Dan' ... } - create new command for performing startBIT, changeChannel or turnVolume

Third design is to represent each operation which can be pronounced as a noun as a resource and the rest as properties:

http://domain/tv/versionUpdates GET | PUT | DELETE | POST

http://domain/tv/BITs GET | PUT | DELETE | POST

http://domain/tv/ PUT ({volume: 10})

http://domain/tv/ PUT ({channel: 29})

What is the best RESTful design?

Answer 1

The third option (with the modifications mentioned below) seems to be the best designed - since REST is about resources and nouns, not about verbs and operations.

The changes I would apply:

• http://domain/tv/firmware GET | DELETE | POST

  I'd change versionUpdates to firmware - seems to be much more self descriptive. What's more it seems that PUT operation here doesn't make any sense - you probably do not know the new version of firmware a priori. So GET returns current firmware version, DELETE removes the latest and restores the previous, POST looks and installs for the latest one.

• http://domain/tv/BITs GET | POST

  Here it seems GET and POST will suffice. You just need to GET the results of all tests or of a particular one or just POST new test.

• http://domain/tv/ PATCH ({volume: 10}) and http://domain/tv/ PATCH ({channel: 29})

  Since both are very similar - I'd change PUT to PATCH - remember that while using PUT you need to include the whole object - that is - every property. PUT is also idempotent operation. While using PATCH you can change just a single property.