Media Types and Resource Types

one of the central points of REST is that it is resource-centric, and that learning about new resources should be done by following hyperlinks found in previous resources. how to discover these links of course depends on the types of resources a client is dealing with, which means that the ability to understand resources plays a central role in REST.

what we've recently been running up against is the fact that understanding actually happens on multiple levels, and based on these levels, more or less sophisticated ways to use a service are possible. some examples:

• site navigation links on web sites often would allow very sophisticated understanding of the major resources the site provides, but since HTML has no good way of exposing that information, it is not possible to extract the full richness of the links contained in the typical navigation menu. the best case in this scenario would be to have something akin to sitemap in machine-readable sitemap format, but there is no such thing.
• for specific types of pages (let's consider product pages on some major online retailer) it would be possible to get more specific links regarding a product if the layout (i.e., the type of the page) would be taken into account. this of course breaks as soon as the layout is changed, but given that only few web sites are carefully managing their @class and @id, this at least works well as long as the layout remains stable withing these limits. in this case, the layout of the page provides important semantic hints.
• looking at machine-readable formats, it is interesting to look at Atom. because it is based on XML, it could be served as application/xml, but because it is well-known, it should better be served as application/atom+xml, so that clients understand it's Atom and not just XML, and so that clients can specifically request Atom. however, if it contains additional information such as GeoRSS or feed paging, this cannot be signaled by the media type, but instead it needs to be found out by inspection on the client side. and since there is no media type for these formats, there is no RESTful way to request a GeoRSS or a paged feed.

all of this means that while the theory of only looking at media types and requesting media types looks well in theory, in practice (in particular when embedding something into an existing set of resources and media types instead of starting from scratch) it often is necessary to make assumptions about resource types based on media types and additional hints. these additional hints can be resource inspection, or they can be URI pattern matching. in particular the latter makes many REST folks see red, but i am really wondering whether this isn't something to consider as well when working with existing services or simply describing them as good as possible.

in the end, we want to build an application that starts with a URI, interacts with the URI through a given protocol, processes the resource received as a result of that interaction, continues by discovering links in that resource, chooses the appropriate link type and link instance for the next interaction, and eventually continues this cycle. if the problem of better understanding a resource's semantics can be improved by inspecting the resource itself or its URI, while the primary method of designing interactions still is based on finding links and following them, then things still should be pretty RESTful, even though not in the most ideal way imaginable.

i guess the main issue here is when to promote a pattern or a property of a class of resources to mediatypeness. if some class of resources exposed by a service has useful links in them, and they are not exposed as a specific media type, then there has to be additional information that can be used to identify a resource as a member of that class, so that you can build richer interactions with it. why this may stray from the purist path of REST, for our purpose of describing RESTful services (or almost RESTful services), this is the way that seems to make most sense, pragmatically speaking.