Tuesday, June 8, 2010

Please Accept: application/hal+xml

Here's an example of something I'm calling the 'Hypermedia Application Language' (hal):

http://gist.github.com/430011

Hal just defines a standard way to express hyperlinks in xml via a simple <link> element. The link element has the following attributes: @rel @href @name
  • Simple links can be written as solo/self-closing tags.
  • Links used to indicate embedded representations from other resources should be written with open and close tags, with the embedded representation contained within.
  • The root element must always be a link with an @rel of self and an appropriate @href value.
  • @name must be unique between all links in a document with the same @rel value, but is not unique within the entire document. i.e. a link element cannot be referred to by @name alone (thanks to Darrel for this)
  • @href value may contain a URI template
Some questions that have arisen for me:

What can/can't you do with this media type?

Did I just reinvent RDF/XML?

Is it enough to implement a system with this media type and to provide documentation to clients as "application specs" or "flow specs" describing the various ways link relations can be traversed to get stuff done?

As usual - all thoughts, comments, suggestions welcome! :)

8 comments:

  1. Hi Mike,

    IMHO you did not reinvent RDF/XML, but a bit of Atom and a bit of standardization of what @mamund describes here: http://www.amundsen.com/blog/archives/1041 ("bit" not in a negative sense). Will it (application/hal) make our lives easier? Maybe, if everyone implements it. I think getting media type documentation right (so that people know what to expect [and thus not have the need for a @method={GET|POST|PUT|DELETE|PATCH} attribute that some (including me) have been thinking of]) is way more important. This, plus a reliable (i.e. semantically well defined) set of values for the @rel attribute could already be good enough.

    Cheers,
    Tom
    @tomayac

    ReplyDelete
  2. Addendum: application/hal should be application/hal+xml of course.

    ReplyDelete
  3. Personally, I think this is bad, because with this the <link> element has suddenly become ambigious and all the meaning is then pushed to the attributes and containment relationship of elements. Also, it's very difficult to read.

    As your question asks, to me, it does in fact look a lot like RDF/XML.

    ReplyDelete
  4. As you might suspect, I like this idea.

    some suggestions:

    if @name must be unique in a set (same @rel), why not use @id instead?

    is @rel only a "group name"? IOW, is it an object like "list"? if yes, are things such as @rel="edit" not valid w/ hal?

    can @rel be a whitespace separated list of values? (@rel="item edit")

    for easy access via machine processing consider using using elements to outline content in a link:
    [link]
    [data id="name"]...[/data]
    [data id="age"]...[/data]
    [/link]
    What about query templates (FORM method="get")? and write templates (FORM method="post|put|delete")?

    ReplyDelete
  5. I've asked a question about this same thing on stackoverflow (http://stackoverflow.com/questions/3014016/on-rest-wadl-or-not-idl-is-the-following-approach-right), Darel Miller pointed me to your post.
    I like this idea ! One thing i'd add is a resource element and a type attribute on the link element. The latter would make it easy for the client to know in advanced if it can deal with the linked resource.
    The resource element would be the abstract representation of any resource. I'd use that as the root of your document (instead of link).
    As for "title" and "content", do you think these are useful to machines ?
    An other thing i have been thinking about for links that modify a resource (POST or PUT) is to have something similar to forms and it seems mamund has bought up this question. Basically this would be something about including a structure inside link for the client to know how the server expects the input.
    Great to know that a lot of people are interested in such a thing. Actually REST defines abstract concepts and it sure would be great if it defined an implementation of these abstract concepts.

    ReplyDelete
  6. Hi @mamund! :)

    "if @name must be unique in a set (same @rel), why not use @id instead?" - to avoid confusion with uniqueness of @id html

    "is @rel only a 'group name'? IOW, is it an object like 'list'? if yes, are things such as @rel="edit" not valid w/ hal?" - I wouldn't say not valid, just not (imo) good practice. They're still just resources.

    "can @rel be a whitespace separated list of values? (@rel='item edit')" - yes

    "for easy access via machine processing consider using using elements to outline content in a link" - do the data elements need to be generic in that way? What does the system gain from that?

    "What about query templates (FORM method="get")?" - no need because you can use URI templates for that

    "write templates (FORM method="post|put|delete")?" - machine client's don't need write templates/forms, they should be written against the latest definition for the link rel in question, that is contained in the system's documentation.

    ReplyDelete
  7. Hi Reda,

    All elements other than <link> are intended as example elements that could be contained in a hal representation, these should be established/defined in documentation of the system against the appropriate link relations. So in this example context <title> and <content> would be defined in the documentation for the link relation "item"

    @type is a possibility, but the current wisdom on its purpose within RESTful applications renders it somewhat meaningless, imo, so I'm leaving it out for now. Client's should express their preferences for media types in the Accept header, and the server can respond with a 406 if it can't provide anything acceptable. Some costs incurred for 'unnecessary' requests, but nothing major.

    I'm not fond of the idea of a root resource element, it's implicit from the action of dereferencing a URI.

    I'm also yet to be convinced of the usefulness of forms for machine clients, it bloats the representation and doesn't actually solve the real problems. With forms; machine clients will still have to 'couple' themselves to a fixed assumption of what can be put into the form; if you add inputs into the form a developer will still have to update the machine client to make that happen - at which point why not just communicate the 'form' within the documentation for developers and leave it out of the machine representation?

    The primary reason HTML forms work so well is that they are aimed at humans, not machines. Human's can make intuitive decisions based on graphical and natural language clues/inference - this is something that machines just do not do right now. I don't think that distinction should be taken for granted! :)

    ReplyDelete
  8. Hi Mike,
    @type i see what you mean. The problem with type is that it means syntax+knowledge. For example imagine a standard for travel business. you could have application/travel+json, application/travel+xml . What i am interested in is the knowledge part. As you say, a client might prefer json over xml. But it needs to know about the semantic to actually do anything with the linked resource. My point is that there has to be some way to hint the client about what it should expect.

    As for forms, the goal is for complexe paramters that just can't go in the url example.com/myresource/{param}. Mainly for filtering and search related resources. Like Air fare search for example.
    If it bloats the representation, this might have its place in a response to a HEAD method of the resource.


    Well for the resource part, don't you think a link in a link looks a bit strange semantically talking ?

    ReplyDelete