AsynchronousBlog

Dave Megginson continues with his REST design questions. Herein, I respond:

Question #2 …

Yup, I’ve used query-paramaters in the way you describe to paramaterize a large resource space. I don’t consider it particular inelegant or ugly, but maybe that’s a matter of perspective…

I believe that retrieving the “container” resource should respond with a form, indicating something like … “the resource is large, and supports paging, and the following values can be used to paramaterize the resource-space: * offset:non-negative integer * count:bounded integer:0..50 * sortCode:enumeration{ * ‘name’: ”’sort on object’s name”’ * ’size’: ’sort on object’s size’ * …} * sortAscending:boolean “

As HTML has its forms, we probably want media-types tailored to machines … either a new level of user-agent mediating for the user, or an autonomous one.

One of the more annoying issues I’ve run into with this is documentation of the cross-parameter interaction of complex query-spaces. Once things become a flattened name-value-pair list, I don’t believe you actually lose representational complexity (vs. submitting, say, a QueryParam struct on a more traditional procedural API), but you definitely lose representational ease. You may have to do things like lexically-structure your paramater-names, or disambiguate them. That bit is pretty inelegant, true.

Question #3

Links means whatever is specified by the format defining the context in which link appears. For instance, html:a@hrefroughly means “this is the the location that should be travesed to in the user agent when the contained object is clicked on”, or something. In the @xmlns case, yes, it does not mean what html:a@href means, but why should it?

And, yes, while the URIs which are used for most xmlnses don’t resolve, this is a bad thing, specifically for the reasons you’re getting at — HTTP URLs should resolve. This is especially true for namespaces, IMHO, because more often than not the semantics are implicit and unknown, unlike HTML where it’s expliclit and well-known.

Yes, there’s some nice ideal world where a spider can simply GET deeper and deeper into information resources. And in a RESTful web, that may even be very true. But it’s a bit naive to believe that at some depth the crawler doesn’t need to understand a least a bit of the document semantics — in fact, an important part of Fielding’s dissertation is that the HTML semantics are wide-spread and well-known.