RESTful Web services and DAL

[Guy Rixon]

Doug,

I suggest that there are two distinct uses for parameters associated with a
web resource. One is to identify the resource: in this case the parameters are
part of the URI. The other is to specify a state-change to the resource which
persists beyond one HTTP exchange: this is always a posted request.

Therefore, I can say

 http://etc.etc/SIA?queryNumber=42
 http://etc.etc/SIA/42

and they are equivalent. If I want to change the timeout of a running query,
then I mustn't GET

 http://etc/etc/SIA?queryNumber=42&timeout=100

because I'm changing the state of the resource. This GET won't always work.
Instead, I have to post

  timeout=100

to

 http://etc.etc/SIA?queryNumber=42

This works and is robust; but is it clear? What would the web form look like?
Maybe queryNumber has to be sneaked in as a hidden parameter. For me, it's
much neater if the URI path identifies the resources and the query parameters
identify the changes. This only shows up when you move to stateful services
(=asynchronous queries) so hasn't mattered in DAL services so far.

The other difficult case is when a resource has children. If I have

  http://etc.etc/SIA/42/
  http://etc.etc/SIA/42/progress
  http://etc.etc/SIA/42/result
  ...

then I can immediately see how they are related. I know, for example, that
deleting the /42 resource deletes also the children. In some visions of REST,
it is good practice that the /42 resource itself is a list of links to the
child resources.

If instead I have

  http://etc.etc/SIA?query=42
  http://etc.etc/SIA/progress?query=42
  http://etc.etc/SIA/result?query=42

then it still works - it's like normalizing a relational database - but one
has to stop and work out what happens with the state changes. What is got from
/SIA?query=42; what do I get if I leave out the parameter? What if I delete
/SIA?query=42? Do /progress?query=42 and /result?query=42 go away as well? Or
do they stay? Or does one go and the other hang around? It takes relationships
that were obvious in the path-baed form and forces us to explain the details
in the spec.

For these reasons, I prefer the path-based URIs when designing services with
ephemeral resources, as in UWS. It's easier for my poor, tired brain.

Cheers,
Guy

On Tue, 13 Mar 2007, Doug Tody wrote:

> On Tue, 13 Mar 2007, Doug Tody wrote:
> > A key characteristic of RESTful services appears to be an attempt to
> > represent resources and state as "[file-like]" references, i.e., URLs in
> > the case of the Web.  In Unix file system terms, /proc is an analogous
> > mechanism.
>
> > This would seem to work well for state, but a strict path-oriented
> > approach (as in http://blabla.edu/cutout/301/22/bombayduck) does not
> > work well for service operations.  Operations are hard to define [without]
> > some sort of parameter or argument mechanism.
>
> I may be enlightening to look more explicitly at the /proc analogy.  If on
> my Linux system I look at process pid=21 I get:
>
>      % ls /proc/21
>      attr  cmdline  environ  fd        maps  mounts  stat   status  wchan
>      auxv  cwd      exe      loginuid  mem   root    statm  task
>
> which tells me about all sorts of interesting information I can
> retrieve, without my ever having to read about kernel process
> structures.  Then I can do
>
>      % cat /proc/21/status
>      Name:   khubd
>      State:  S (sleeping)
>      SleepAVG:       98%
>      Tgid:   21
>      Pid:    21
>      PPid:   1
>      TracerPid:      0
>      Uid:    0       0       0       0
>      Gid:    0       0       0       0
>      FDSize: 32
>      Groups:
>      Threads:        1
>      SigPnd: 0000000000000000
>      ShdPnd: 0000000000000000
>      SigBlk: fffffffffffffeff
>      SigIgn: 0000000000000000
>      SigCgt: 0000000000004100
>      CapInh: 0000000000000000
>      CapPrm: 00000000ffffffff
>      CapEff: 00000000fffffeff
>
> which returns a simple block text containing parameters describing the
> process, i.e., a set of keyword-value pairs (easily machine readable
> despite not using XML).
>
> This would seem to be a good illustration in more familiar
> terms of what is intended by the REST approach where we merely
> use the Web instead of a Unix file system.  File URLs are used to
> address resources and state information, in this case the state of a
> long-running process.  The mechanism is simple but powerful; standard
> protocols and tools (ls, cat) can be used to access this information.
> In get analogous Web case we could use things like wget or curl.
>
> Note however, that while this mechanism can be used to "get" state,
> and given sufficient permission we might be able to "put" bytes to a
> file interfaced via /proc or /dev, we don't use these mechanisms to
> *run* a process.
>
> To run a process (change the system state) we execute a command,
> using a shell or the exec system call, or we invoke an operation on a
> kernel service or daemon, and so forth.  This may result in new state
> information showing up in /proc.  For example "/usr/bin/cmd <args>".
>
> The analogous "execute" operation on the Web is GET or POST, both of
> which can execute a command with parameters.  In this case the Web
> goes one step further than Unix, as *merely reading* an executable
> file is allowed to transparently execute the file.  GET defines
> a syntax which allows the command arguments to be folded into the
> command reference as one long string, the URL.  A clever Unix file
> system driver could be written to do this same thing.  POST is a more
> explicit command invocation, which separates the command arguments
> from the command reference.
>
> In short, REST is basically just the Unix "file" concept mapped
> onto the Web, with GET serving a clever dual role.  As a result,
> standard protocols and tools can be used to do useful things.  SOAP is
> (primarily) an RPC protocol, defining a standard encoding to invoke
> a remote method on a object.
>
>  	- Doug
>

Guy Rixon 				        gtr at ast.cam.ac.uk
Institute of Astronomy   	                Tel: +44-1223-337542
Madingley Road, Cambridge, UK, CB3 0HA		Fax: +44-1223-337523