2008/10/22
It’s good to see Roy take on the pseudo/not-at-all “REST APIs” out there.
As I mentioned in a comment there, I’m no stranger to this kind of interface specification, as I’d guess that about 80% of the “APIs” I reviewed as a consultant suffered from at least one of the problems Roy listed. Fortunately, I found it wasn’t very difficult to get people to see the error of their ways. All I had to do was re-emphasize that REST requires that interfaces be uniform – the same – and therefore that pre-specifying anything specific about a resource, such as URI structure, response codes, media types, resource relationships, etc.. was antithetical to that requirement.
Thanks Mark,
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.
I would suggest using a new media type that is built with JSON, but specifies where URIs go.
Thanks Mark.
I’m not entirely sure I understand how resource relationships can be made 100% discoverable. Let me use a concrete example:
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.
oh darn… it cleaned up the response in my example. I’ll do it in json instead:
{
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.
You’re on the right track, Brian, but I’m not sure how you conclude “but I don’t know what that means”; that shouldn’t be the case if the rel type is well specified. Instead of the hypothetically ambiguous “related” rel type, consider what it would mean to use the registered rel value “author”; you would know that the Foo resource is declaring that it considers the Bar resource to be its author.
@Mark, I know it has been awhile since this post was originally posted, but I had a comment/question in regards to your last reply.
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””.
Kevin – by “rel type” there I mean the same thing Roy means when he says “relation name”. Perhaps that’s a poor choice of terminology on my part, but it’s how I think about relations (and it seems you do too). That’s fine IMO, as long as we recognize that there’s no connection between the relation and resource types, i.e. for that previous example, using an “author” relation is *not* a declaration that the publisher believes that the target resource has a resource type of “author”, it is purely a statement about the relationship that exists between those two resources.
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”.
I think I’ve finally wrapped my head around what Roy really means by RESTful APIs with the discovery bits and all, but I really just do not see the point for any application where you produce the one and only possible client to your service.
For a public API, I think I get it. For a private one, though, this level of decoupling seems completely academic and entirely not pragmatic.
Not entirely sure I understand your point, Guyson.
Using a common interface doesn’t mean there’s only one client, or even form of client. Quite the opposite in fact, as the generality of the uniform interface makes your data/application maximally available.
As for public vs. private, you’re right that the properties provided by REST aren’t necessarily as valuable in private contexts. But I wouldn’t necessarily discard them without first understanding what they can buy you, especially if you’re still using the Web.