So, a bunch of us were sitting in the hotel bar last night, and came
to the conclusion that it would be useful to start capturing
information about Web description in a more organised fashion. As a
result, I've seeded a bunch of pages on the W3C's ESW wiki, starting at:
One of the more interesting -- and promising -- things we discussed
was the thought of capturing patterns of use for HTTP.
A description format -- inevitably -- can't describe everything about
an application; by its nature, it's incomplete. One of the problems
I'm concerned about is that because of this, any description format
that gets standardised (or even widespread adoption) will unavoidably
encourage some patterns of use and discourage others. Note that this
isn't the case with existing prose descriptions of Web APIs; it's
only when you try to abstract out a generic description format that
you have this problem.
Therefore, it would be best to collect patterns of use by examining
existing Web applications, APIs, standards that use HTTP, and tools
that implement it, so that we can figure out which patterns are
common, which ones give the most benefits within the architecture,
and so forth. With some work, this will help inform the creation of
formats so that they don't needlessly cut off some applications, or
encourage bad patterns (for some value of bad).
Look in WebDescriptionExamples and WebDescriptionPatterns for more
(and to add!). I've just listed a few potential patterns to start
with, and will try to flesh them out in time.