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

[Aristotle Pagaltzis]

* Ian Docherty <catalyst at iandocherty.com> [2008-01-28 13:45]:
> OK, so I put the item into the request body, but this does not
> tell the remote client the ID of the created item.

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)?

> Say for example that I am putting arbitrary documents (xml,
> text, images) etc. onto the server via a web service in a
> RESTful manner, I do this with a POST to my server. The server
> needs to respond with something in the header to indicate the
> ID of the document just POSTed.

Well, then don’t render the body of the item in the 201 response,
and do not set Content-Location, and instead just put some JSON
or XML or whatever in there.

> I do this in the Location header.

Location may only ever be a URI. If you put anything else there,
you’re doing it wrong.

> e.g. POST /svc/upload (the document save)
> Location /svc/view/1234 (the location of the item just saved, ID=1234)
>
> So the URI is parsed by the programmatic client to extract the
> '1234' yes/no?

No. Clients should never parse URIs. If you need to tell them
something they need to be able to understand, you put it in the
body.

(They should not construct URIs either. If they need to request
parametrisable URIs, the server should send them a form. Or if
you’re creating a non-browser HTTP API, you can send the client
a URI Template.)

This is the hypermedia constraint in REST: clients only follow
links and forms. They don’t have any hardwired knowledge of the
server URI space.

(Note, though, that things get muddled with Ajax clients. If the
Ajax client is code served by the server (called _Code on Demand_
in REST), then it’s effectively a Turing-complete kind of form
markup, so it’s fine for that code to have hardwired knowledge.
But in practice, the Ajax client probably talks to a publically
available HTTP interface, and making that interface require hard-
wired knowledge of non-Code-on-Demand clients is wrong, so it’s
probably better to follow the hypermedia constraint even in on-
demand code.)

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>