« Grand Canyon Rim to Rim to Rim | Main | Workshop on RESTful Design 2012 (WS-REST 2012): Call for Papers »

Sunday, November 06, 2011


Feed You can follow this conversation by subscribing to the comment feed for this post.

Ruben Verborgh

This is an interesting approach – but are the two different URIs really necessary?
While I like the mechanism "token/definitive URI", I don't see the benefit of actually having two URIs.

Would this proposition, with only one URI, have different effects?
1. GET for template and token URI (no resource created yet)
2. PUT to token URI – the token URI was an uninitialized resource (404) but no becomes a resource (200)

I think it still has the same benefits, but a little less complexity.

And also: how is your token generation going to work? Do you use GUIDs or an incremental counter (which could insanely increment without serving a purpose)?


@ruben, thanks for the comment. one goal we have is to provide "nice" URIs as the persistent identifiers for resources, and for our back-end architecture, this means to reuse the internal identifier as part of that URI. however, that identifier is only known after the resource has been created in the persistence layer. i agree that in principle, you could get away with just using one identifier and simply remember whether it had been initialized before, but then you don't have the opportunity to use the persistence ID as part of the URI.

Daniel Schulte

at first I was surprised to see a solution for the "POST Once" problem without using the POST verb. But now, I see several advantages, e.g., the option to use content negotiation before creating a new resource and the option to provide a form (instead of or as part of a template).

However, as you focus on the idea to use GET+PUT, I have questions with respect to technical details:
- Browsing a RESTful application (a collection, ...), a client needs to know, where and how to add resources using the GET+PUT combination, i.e., in the first step, it needs to know, where to get the template. A link relation can specify that the provided URI allows to add resources using GET+PUT with templates (and in my opinion the link relation should be independent of the context as it specifies a procedure; a further link relation may state more precisely what kind of resource may be added). Do you have any link relation or another approach in mind?
- How should I provide the URI for PUTting the filled template? As a link header with some special link relation?
- I also like Rubens point and I think in many use cases one URI will be enough (even though it might be less nice). I see no problem in supporting both options. If the client gets a 201 Created, it knows, the PUT was successful (I would only use 200 OK for subsequent PUTs) and it already has the URI of the new resource. If it gets a 303 See other, it knows, the put was successful and the new URI is provided. And clients should be able to handle 301 not only after creating resources. Did I missed any potential problem in supporting both options?



daniel, thanks for your comments! here are my responses:

1) how to link to the factory/template: yes, i think there should be a link relation. it simply would be a relationship defined for this pattern. with AtomPub, this is easy because you just POST to the collection URI, so there's not additional resource involved. for the GET/PUT pattern, this is different, and we will need to have a link relationship for that.

2) returning the PUT URI: http://tools.ietf.org/html/rfc2616#section-10.3.4 says that the 303 response should return the new URI in a Location header, and thus that's probably more appropriate than a Link header.

3) using the token URI as persistent URI: that's not something we would like to do because we want the token to be transient, and we want the persistent URI to reflect an internal id. but i don't think the pattern would change at all if you used the same URI, the only difference on the implementation side would be that instead of storing the token with the persisted object, you would add a switch to the persisted object saying uninitialized/initialized.

thanks for the comments! i am planning on documenting this a little better, any feedback what you would look for would be welcome.

Daniel Schulte

Thanks for your explanations. My second question was a bit ambiguous, sorry. I like to know, how to provide the link to the resource where I have —as a client— to PUT my filled form to (the link in the response to the first GET to receive the template, not the response to the PUT-request).

I'm looking forward to your more detailed documentation as I am really interested in this topic. One of my students currently analyses different POST Once proposals (http://fernuni-hagen.de/dvt/studium/masterarbeiten_12.shtml, nearly finished) using colored petri nets to model server and client states and interactions. I will try to apply his method and model to your approach next week, then I might have further questions.



mark nottingham's POST Once Exactly (POE, http://www.mnot.net/blog/2005/03/21/poe) is probably pretty much what i've described here, as usual going back to the history books is a good idea. mark has pointed out that the pattern and the required information could be used by extending HTTP, or by embedding appropriate information in representations. since POE hasn't made it as an RFC, i guess the way to go nowadays is the "plain HTTP" version described here. as mark notes, the important thing is that the server needs to keep state about whether a resource has been used or not.

so maybe the simplest way to describe this GET/PUT pattern would be to say it implements POE, but avoids POST.

The comments to this entry are closed.