Profiles
Tuesday, 17 April 2012
Erik Wilde - otherwise known as dret - has published an Internet-Draft for a “profile” link relation type:
This specification defines the ‘profile’ link relation type that allows resource representations to indicate that they are following one or more profiles.
Why am I excited? Three words:
Media Type Proliferation
For better or worse, everyone and his dog is minting “RESTful” APIs. One byproduct of this is the need to identify formats, so they’re going off and creating new media types. Lots of them. Sometimes, for every variation of their syntax (e.g., if a new element is added) some people feel the compulsion to identify it with a media type. This quickly gets unwieldy, obviously, and registering that many media types won’t do. Enter the profile relation:
HTTP/1.1 200 OK
Content-Type: application/json
Link: <http://example.org/profiles/myjsonstuff>; rel="profile"
Connection: close
{
"stuff": 0,
"moar-stuff": 1
}
Here, a Link response header is used to say that the application/json content conforms to a particular profile. What that profile is is completely defined by the person who owns that link, so it can place constraints on the contents, advertise conventions, and so forth. This means that you don’t need to define and register a new media type for every message type in your RESTful API (a dubious combination of terms anyway); using a URI means that you can place constraints on the format, advertise extensions and compose them without using top-level media types (which were never intended for that anyway). Media types aren’t so good for this; because they’re a flat, highly-structured space, it’s difficult to describe variations in format with any nuance. Also, by defining a new media type, you lose information about the generic formatting conventions of JSON or XML — something that people are trying to shove into +json and +xml extensions.
Wait, Haven’t We Seen This Before?
Profile was born in HTML, where it’s used by microformats.
<head profile="http://microformats.org/profile/hcard">
Here, the hCard profile tells people consuming the HTML — a format that they already known about which is advertised by the media type — that it conforms to some additional constraints (in this case, a particular arrangement of HTML classes). In Microformats, you can combine multiple profiles to indicate that more than one profile is in effect in the document:
<head profile="http://microformats.org/profile/hcard
http://microformats.org/profile/hcalendar">
Tell Me More.
The same ideas can be used in JSON formats, and once we figure out conventions for linking in JSON, we can embed the profile links inside the document too. Since doing so will leverage the concepts in Web Linking, if we do it right, that means that a profile can be applied to a context that’s part of a document — for example, one object in JSON. E.g.,
{
"thing": { "a": 1, "b": 2 },
"owner": {
"_profile": "http://example.net/name",
"firstName": "Bob",
"lastName": "Roberts
}
}
This has some pretty cool implications for collections in JSON — more on that soon. Note that using link conventions in a document is a profile itself. With profiles, you can say that the http://example.com/b
profile extends the http://example.net/a
profile, or you can mint a new http://example.org/c
profile that combines them; it’s up to you. You could even specify query parameters to control variability in the format, if you really want to.
But, What Should a Profile Be?
Since it’s a URI, it’s possible to dereference a profile URI — just like an XML namespace document. I suspect that it’ll become useful to define a lightweight document format describing a profile, its relationships to other profiles, etc. I’m not sold on pointing to a schema yet (JSON or otherwise). This is kind of the nice thing about profiles; because they don’t require a specific form, you can make them mean what you want to. The challenge, I think, is to come up with conventions and tools that promote good practice and reinforce the Web, rather than turning this into just another layer of media types, or something like WSDL. Erik is still working on his draft, and people (including me) are giving feedback.
21 Comments
http://openid.elfisk.dk/jornwildt said:
Tuesday, April 17 2012 at 5:23 AM
James M Snell said:
Tuesday, April 17 2012 at 7:42 AM
Mark Nottingham said:
Tuesday, April 17 2012 at 8:41 AM
James M Snell said:
Tuesday, April 17 2012 at 9:55 AM
Erik Wilde said:
Wednesday, April 18 2012 at 2:11 AM
Manu Sporny said:
Wednesday, April 18 2012 at 3:11 AM
Mark Baker said:
Wednesday, April 18 2012 at 3:41 AM
James M Snell said:
Wednesday, April 18 2012 at 5:14 AM
Erik Wilde said:
Thursday, April 19 2012 at 5:33 AM
Mark Nottingham said:
Thursday, April 19 2012 at 5:35 AM
Erik Wilde said:
Thursday, April 19 2012 at 5:40 AM
Jan Algermissen said:
Wednesday, April 25 2012 at 7:01 AM
Mark Nottingham said:
Wednesday, April 25 2012 at 7:48 AM
Jan Algermissen said:
Thursday, April 26 2012 at 1:39 AM
James M Snell said:
Friday, April 27 2012 at 3:59 AM
Mark Nottingham said:
Friday, April 27 2012 at 4:01 AM
James M Snell said:
Friday, April 27 2012 at 5:03 AM
Mark Nottingham said:
Friday, April 27 2012 at 5:09 AM
Jan Algermissen said:
Friday, April 27 2012 at 6:53 AM
Mark Nottingham said:
Friday, April 27 2012 at 10:38 AM
Mike Schinkel said:
Wednesday, July 4 2012 at 5:01 AM