« Generalized HTTP Content Negotiation | Main | Future-Proofing REST Clients »

Tuesday, September 10, 2013

Comments

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

Ruben Verborgh

I like the idea of being able to create specific functionality and affordances by composing it from more elementary pieces.
I might have missed this previously, but how can we negotiate on the supported profiles?

Peter

The app:collection element can be included in the atom:feed element. In the app:collection element, an empty app:accept element indicates a read-only feed. Media types listed in app:accept can be POSTed. http://tools.ietf.org/html/rfc5023#section-8.3.4.

dret

@ruben, i don't think that profiles are quite on the level of media types (for which negotiation is baked into the fabric of the uniform interface). i see where you want to go with this (i think), and at some level you could say that you could negotiate by using Accept and adding a profile media type parameter. or you could go wild and dream up an Accept-Profile header to avoid this "overloading" of Accept. but at some point, things start to get a little complicated... in the end, profiles are just a simple way to expose/encode the "specialization" of a media type, and they are not full-fledged media types by themselves. it actually would be interesting to go through a systematic comparison of where minting new media types, and using profiles, differ, and also, what might be added to the picture (such as the hypothetical Accept-Profile).

dret

@peter, thanks for pointing that out. that's a rather interesting definition of defaults there, saying that 'If no app:accept element is present, clients SHOULD treat this as equivalent to an app:accept element with the content "application/atom+xml;type=entry"'.
this seems to define that every non-AtomPub feed (because it will not have app:accept in it) will always be treated as saying "i am an AtomPub feed" by AtomPub-aware clients. that's one way of doing it, but makes it hard for clients to leave pure Atom feeds alone by understand that they can probably not be POSTed to, if they don't exhibit any signs of AtomPub being supported.

Peter

@dret Not quite, because the app:accept element is in the app:collection element which MAY be present in the feed. If you include the app:collection element, you are by definition AtomPub, obviously, but the POSTability then can be determined by the app:accept. The PATCHability may be a good candidate for a profile, however. I think another approach might be an extension of the app:collection control with something relating to PATCH, perhaps based on how the app:accept (POSTability) is modelled. For me, app:collection is the core of a powerful hypermedia control. Thanks for your excellent blog.
Cheers,

dret

@peter i should have looked closer. i was assuming you can use app:accept on a feed, but you cannot. it can only be used in service documents. but then again, doesn't this mean that my original claim is true that when you just look at a feed, you cannot tell whether it supports AtomPub or not? it may link to a service document, but that's not even supported by AtomPub itself, but only by the "service" link relation which RFC 5899 defined later on.

Ruben Verborgh

@dret Thanks, that was indeed where I was going. Especially the decision of when to use a media type and when to use a profile could be an interesting topic. Perhaps Accept-Profile could make media “subtypes” (like +json etc.) obsolete and allow much more fine-grained control.

Peter

@dret Actually, the app:collection element is an optional child element of atom:feed, made so by AtomPub. Of course it is mandatory in the service document (if a collection exists). A typed link to the service document might be enough to tell you it's an AtomPub feed, but as you say that's an extension not defined by the application/atom+xml;type=feed type. If the service *does* decide to include the app:collection element, I think this helps with the HATEOAS constraint, because, by inspecting the *representation*, the client is made aware of next (possible) states. Perhaps having a service document linked, out there is good enough, but I like the explicit inclusion of the hypermedia control *in* the representation. In that case there's no ambiguity then about whether a POST came just out of the blue or was guided/ encouraged by the server.

Cheers,
Peter

dret

@ruben: as a general rule, you should only use profiles if the representation also can be interpreted in a meaningful way without knowing the profile. a podcast is a profile of a feed (it makes sense to look at a podcast feed without knowing that it is a podcast). but a feed is not a profile of xml, because when you look at feed XML without knowing that it is a feed, all you see is a generic XML tree of elements and attributes: a very different thing altogether.
it is important to keep in mind that profiles try to capture this "you can look at this as a podcast or as a feed" scenario, whereas the "+xml" suffix really just tells you: this representation happens to be serialized in XML. so for example for home documents, we can mint application/home+xml and application/home+json, and it's kind of obvious that these two have something in common. that's where structured suffixes come in.

dret

@peter, i have to admit that i completely forgot about app:collection being allowed as a child of app:feed. and yes, in this case you're right that it's good hypermedia. what's happening there is basically a protocol-specific form of an "allow-post link hint" http://tools.ietf.org/html/draft-nottingham-link-hint#section-3.4 or an Accept-Post HTTP header http://tools.ietf.org/html/draft-wilde-accept-post
and i guess this is what profiles and some other things i have been playing around with come down to: they are approaches of how to create specs that encode and harmonize certain design patterns that we've seen popping up in various places, and in various forms. i am not saying that all of this is the best or the only way to do it, but once you've seen a number of services doing this in a variety of ways, it makes sense to at least think about if and how it could be turned into a standardized and thus easily reusable and understandable component.

Verify your Comment

Previewing your Comment

This is only a preview. Your comment has not yet been posted.

Working...
Your comment could not be posted. Error type:
Your comment has been posted. Post another comment

The letters and numbers you entered did not match the image. Please try again.

As a final step before posting your comment, enter the letters and numbers you see in the image below. This prevents automated programs from posting comments.

Having trouble reading this image? View an alternate.

Working...

Post a comment

Your Information

(Name is required. Email address will not be displayed with the comment.)

Flickr