media types are one of the foundations of web architecture: media types allow clients to understand the
rules of engagement, so that interpretation of state, as well as subsequent interactions, can be driven by that shared understanding. ideally, new services are not reinventing everything and create their complete own set of media types they are using: often they expose a mix of custom media types, reused media types, and some rules of how this web of resources is interconnected by navigable links.
as a little exercise in how such a setup might work and could be made self-describing, let's assume a service uses Atom as a general mechanism for how to represent collections of various kinds, and AtomPub as a general mechanism for how to enable write access to (some of) those collections. this example simply uses parts of the Atom Landscape, but the general pattern in applicable to any scenario where media types are reused, and their usage is refined by additional constraints/extensions.
to make things more interesting, let's also add
AtomPatch, a hypothetical additional protocol that complements AtomPub by adding support for the HTTP PATCH method on collections. let's assume AtomPatch allows you to POST a feed of to-be-patched entries to a collection, either updating entries completely, or using Atom Tombstones to indicate that an entry should be removed (we're actively looking into this as a way to handle
bulk updates to a collection, but that's a different story than the one i am telling here).
the interesting question is how to make all of this as self-describing as possible. when GETting an AtomPub/AtomPatch enabled collection, there is no link in there telling a client that there are additional interaction capabilities to that resource (POST because of AtomPub, and PATCH because of AtomPatch). AtomPub defines the an additional
type parameter for the Atom media type, and because that is defined by AtomPub and not Atom itself, it is assumed that if a URI responds with
application/atom+xml;type=feed, it must be an AtomPub collection and thus clients might want to try POST. but this model breaks now that AtomPatch may or may not be supported: how would a client be able to understand this additional level of information?
this is where the concept of a Profile (explained in this blog post) enters the picture: it allows services to expose the fact that a resource is following one or more profiles. for the example of a AtomPub/AtomPatch-capable collection, profiles could be used in the following way:
<feed xmlns="http://www.w3.org/2005/Atom"> <link rel="profile" href="urn:ietf:rfc:5023"/> <link rel="profile" href="http://example.org/AtomPatch"/> ...
this example uses the AtomPub Profile URI proposed in the Atom Profile draft, and makes up a profile URI for AtomPatch. at its core, though, this draft proposes that
application/atom+xml supports a profile media type parameter, so that the
AtomPatch-ness could also be exposed on the media type level as follows:
this way, the AtomPub and AtomPatch affordances of the resource are represented both in HTTP's uniform interface (in the media type), and in the representation itself (by exposing the profile URIs in the generic linking element). the interesting twist here is that the interaction affordances of a resource are not represented as navigable links (as defined by link relations based on Web Linking), but instead they are implied because of the capabilities that clients recognizing the profile URI know they can imply.
it is a design decision whether the fact that some resource is extending a media type should be exposed as a profile, or just by adding links to a representation. AtomPatch could also be defined as using a
patch link relation, and exposing this on all PATCHable collections: the protocol would then be to always follow that link with PATCH and the patch format (instead of always PATCHing the collection URI itself).
what profiles allow is a convenient grouping of capabilities: in the same way as a media type often bundles a number of interaction capabilities that probably all should be supported (or at least considered) by clients, a profile does the same for services that are based on existing media types, but constrain and/or extend them. profiles may make it a little easier to make resources self-describing, by referring to an additional context that is optional to know for a client, but may provide additional information about a resource's data model and/or hypermedia affordances.