You can define your own rel types too of course, but that comes with a cost, so try to minimize that cost by registering any generally useful ones, and reusing existing ones wherever possible including when you’re also using a custom one (as a fallback). As an example of the latter case, if you were writing a music app, instead of just saying rel=”composer”, you could use rel=”composer author”.

From what I read on Roy’s post, comments, etc, typing of a resource seems to be a big part of the confusion (what is this “thing” you are referencing), and perhaps mine as well. While I’d agree that the type used in the server implementation vs. the client implementation doesn’t matter, you are indeed typing resources, per the quotes below. Is “author”, given in your example, not a type? Why, if this is the case, can the 2 not be mixed? Why can I not define my own types extending on standards (or can I?)? Am I missing something?

Roy: “The only types that are significant to a client are the current representation’s media type and standardized relation names.”

You (last comment): “that shouldn’t be the case if the rel type is well specified. [...] consider what it would mean to use the registered rel value “author””.

{
links: [
{
"rel": "related",
"method": "GET",
"type": "application/vnd.custom.bar+json",
"href": "/some/url"
}
]
}

So I know that I can GET a related Bar… but I don’t know what that means, unless the relationship of a Foo to a Bar is prespecified.

I have a Foo, and I do a get on it. Among the options for state transitions I have available is a link to get a Bar.

Now assume that my client knows what a Foo is, and it knows what a Bar is… how does it know what this Bar MEANS in relation to this Foo?

I considered rel tags, so something like this:

HTTP/1.1 200 OK
Content-Type application/vnd.custom.foo+xml

But, that doesn’t tell me anything, unless we assume that the semantic meaning of this particular link is implicitly part of the definition of application/vnd.custom.foo+xml. And if that is true… then we have “prespecified” the relationship.

I also read Roy’s post, and it was (rightfully) disciplinarian.

I want to get my API inline with REST completely. Most of the basics are covered (I think): keeping resources, methods, content types separate. GET, POST, PUT, DELETE. Digest Authentication where necessary.

My concern, and what I’m trying to find out more about, and where I don’t meet Roy’s standard, is when it comes to make resource relationships and URI’s discoverable. I.E. hypertext linking etc.

My representations are all in either JSON or XML. Obviously putting any kind of URI link in a JSON object is NOT discoverable. So it has to go in the header right? What would you suggest? More explanation regarding this subject would be very helpful. Forgive me if I’m asking for something you’ve already published.