Hello,

I'm having a hard time designing a restful domain specific XML
vocabulary. How should I link to other resources and others
representations of the resource itself? Atom uses the <link> element,
which is very extensible. But that's its problem, if I am designing a
domain specific vocab, why should I try to be generic? Consider a
client resource. Which may have a collection of orders associated with
it. If I were to point to a resource containing the client's orders, I
could use <link> as follows:

<link rel="orders" type="text/xml" href="/api/client/123/orders.xml" />

The problem I have with that is unnecessary complexity. I'm using a
construct that is clearly intended to be used in broad, extensible
context in a domain specific API that is supposed to be set in stone.
I'm inclined to just use the following:

<client ref="/api/clients/123">
<orders ref="/api/clients/123/orders.xml" type="application/xml" />
<orders ref="/api/clients/123/orders.json" type="application/json" />
</client>

I could definitely find a way to wrap the API in Atom (since
everything are basically collections), and in this case of course I
would use <link>. But if I'm defining my own domain specific API, from
an engineering point of view, should I care with keeping consistency
with Atom/HTML on <link> and potentially also attribute names (ref vs
href)?

I have come up with two postulates for API design, so whenever I would
run into the same type of situation, I would these criteria to guide
myself:

1) Every referred resource within another resource's representation
needs a @ref attribute pointing to its canonical representation
(usually XML), even if it is an empty element, and also a @type
attribute. Example:

<other-resource ref="{uri}" type="application/xml" />

2) Every URI pointing to an alternative representation of the current
resource should be kept as text element children. Naming of the
element for the alternative representation is up to the API specific
domain. Example:

<track ref="/api/tracks/123">
...
<media bitrate="128kbps" type="audio/mpeg">http://...</media>
</track>

What you think of this convention? Am I making any sense here?

--
Jonas Galvez
Software Engineer
Côdeazur Brasil

http://jonasgalvez.com.br
http://codeazur.com.br