(From Brian Moseley via email)

these are some notes i wrote up a while back that I never got around to communicating. I wrote these down one night after reading these blog posts:

http://blogs.sun.com/sandoz/entry/philosphical_content_negotiation

http://blogs.sun.com/sandoz/entry/more_philosophical_content_negotiation

Canonical Feed URIs

The feed service provides distinct URIs for each feed that identify the projection and format of the feed enclosed in the response. The URIs embedded within the feed (for example, the feed and entries' self links) include the same projection and format identifiers.

However, nowhere in the response is the "canonical" URI of the feed, the URI without projection and format information, found. Therefore, if a client wanted to retrieve a feed for the same collection with a different projection or format, it would have to rely on programmed-in assumptions to construct the URI for the new feed rather than using a URI provided by the server. This violates the principle of connectedness which is fundamental to REST and increases coupling.

Furthermore, when a client requests the canonical URI for a feed, it gets back a feed using a projection and format chosen by the server. The server does not provide any guidance as to what distinct URIs are available for the feed.

Recommendations:

1. When a client requests a feed at a "distinct" URI (one specifying projection and possibly format), the response includes a Content-Location header identifying the canonical URI for the feed.
2. When a client requests a feed at a canonical URI, the feed service returns a "300 Multiple Choices" response with an XHTML body including links and text descriptions for each projection and format combination supported by the feed service for that feed.

Content Negotiation

An emerging best practice is to use a suffix rather than a path segment in the URI to specify representation format. Ex:

• /atom/item/{uuid} -> could use the Accept header to perform content negotiation or, if one is not provided, return a 300 as above
• /atom/item/{uuid}.json -> text/eim+json
• /atom/item/{uuid}.xml -> application/eim+xml

Projections

As projection does not denote an actual sub-resource of a feed or item, it's semantically incorrect to include it in the URI as a separate path segment. It's really specifying a dimension or view of a resource - whether or not it has recurrence expansion (full) or triage status (dashboard) semantics. I think it's a little more appropriate to use a path parameter; eg separated from the path segment with a ';' not a '/'. Ex:

• /atom/item/{uuid};full.json
• /atom/item/{uuid};dashboard.xml

Other random notes:

• Rename "full" projection to "recurring" or something like that
• Remove "details" projection and make this a custom XHTML document rather than a 0-entry Atom feed