[Catalyst] Re: REST - like uri design for CRUD

[Daniel Hulme]

On Tue, Jan 29, 2008 at 08:19:42AM +0000, Ian Docherty wrote:
> Aristotle Pagaltzis wrote:
>> Why does it need it? Is the URI not enough? If not, is the URI
>> *really* not enough (ie. could things be arranged so that it is)?
>>   
> The 'create' is a POST to the URI http://mydomain.com/svc/doc with the
> content being the document to save. However, the client has to know
> the ID of the created document (which at this point is only known by
> the server).

I think Mr. Pagaltzis was asking what the client intends to do with the
ID that it couldn't do with the URI of the newly created document. If
you can easily arrange things so that the URI names the document as far
as the client is concerned, rather than the ID, that solves your
problem, and it provides some protection against you needing to change
the format of IDs at the server, or against some replication or recovery
process which (consistently) changes the IDs inside your server.

> This is something I have not seen mentioned before. I have no idea
> what a 'URI Template' would look like. I don't see what is wrong with
> 'constructing' a URI, e.g. what is wrong with the client 'knowing'
> that URI http://mydomain.com/svc/view/1234 is the location to
> retrieve item 1234?

Quite apart from philosophical issues, it makes it harder for you to
change the scheme for URIs. Imagine in a year you (or whoever is working
on the code or managing it) decide that numeric IDs shouldn't be exposed
to the user - maybe because it leaks information about rate of document
uploads, or because it allows people to guess IDs of valid documents.
Or perhaps you (or whoever) leave the ID in the URI but rejig the URIs
so that the ID is in a different place, or so that the creator ID is
included. Obviously, you would want to preserve the URIs of existing
documents, or set up redirects, but I can think of lots of reasons why
you might want to start giving new documents URIs that look completely
different from how they are now.

If your clients just blindly accept the URIs given by the server, and do
not attempt to interpret them, then said clients don't need to be
changed. It means you don't have to worry about a whole test and
deployment cycle, you don't have to worry about getting all the clients
upgraded, you don't have to panic a week after the roll-over because one
person had a long-running session which stopped their client being
upgraded. But if your clients interpret the URI to find the ID, any
change in the URI requires a change in the client.

-- 
"It must be accepted as a principle that the rifle,  effective as it is,
cannot  replace  the effect  produced  by the  speed of  the horse,  the
magnetism of the charge, and the terror of cold steel."
  -- British Cavalry training manual, 1907 ::: http://surreal.istic.org/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.scsys.co.uk/pipermail/catalyst/attachments/20080129/2af384ce/attachment.pgp