REST is an “instance-only” technology with world-wide scope, there are no notion of “classes”, they are only imaginary.

In this content, you would think that someone could spend just a few minutes to define an “id” rel (different from self). Who could think that Identity is not critical to the future of REST in the Enterprise? I don’t know how many times I would have to repeat that Roy designed REST for the Web (with zero enterprise requirements) and who could believe that serendipitously Roy’s REST would match perfectly to every and all Enterprise requirements?

Is it really that much more work to define a precise identity mechanism?

JJ-

I first came across the issue in the context of Topic Maps. Where is it very common to have multiple maps, each with topics that refer to the same subject. Topic Maps are designed to be merged together so you need a way to say that these two topics which come from different sources refer to the same thing. Topic maps share much of the same issues, since a “topic” is to “subject” what a “representation” is to a “resource”.

In topic maps this is done with a Published Subject Indicator; PSIs are simply URIs. Any two topics with the same PSIs refer to the same thing. This has great value, for instance if I maintain a map of topics about Italian Opera and you maintain a topic Map of the CIA World Fact Book (believe it or not these two exist and form the canonical examples for explaining topic maps). In my opera may I have a topic for Milan which is both the birth place of Verde, the setting for several of his plays and the place where Verde wrote some of them. The world fact book has information on the population and industry of Milan. If I combine these two maps, I now have a lot of information about Milan, which Susan could combine with here “tourist places in europe” topic map to help her create a “Opera Lovers Tour of Italy” or something.

I’ve digressed. The point is that Public Subject Indicators may or may not be network retrievable (vis isbn:978-0140283334 which would be a URI for a specific edition of the Lord of the Flies). Any network retrievable resource is treated as a static, human parsable resource; its only purpose is to uniquely identify something.

In an article I wrote on RESTful frameworks I argue that you should not use a REST api for your human intended front end. This is exactly one of the reasons. If you are sending content only to other systems, then you don’t need to have multiple URIs for the same resource; all the logic is left up to the client.

In fact, your examples, I think, are not very good examples for reusable APIs. This example is, I think, the clearest example of bad choices.


GET /myapp/people?like=subbu
Host: http://www.example.org

My issue is with the self links for each of the people. How do you, as the application author, know that the the client wants the mini view? That is a very presumptuous, IMHO, unless you control both the client and your application. Since the reason we publish APIs is that we don’t want to control the clients, I would consider this to be a code smell. Further, the example is missing the even more important link that tells the client where to get a complete representation of of the resource.

I agree that you need someway to identify a resource independently of the URI by which you retrieved it. I do however think that needs to be a URI, and that it should be a URL. If you request this URL, you should NOT get a representation of the resource but rather its meta data. Specifically, I would send URIs for all known representations, their media types and definitions (schemas) etc. Maybe even a simple human readable description.

I would also argue that a more “correct” version of the above representation might be:


GET /myapp/people?like=subbu
Host: http://www.example.org

This is the problem with using “ideal” and easy examples, you miss all the details you discover from a pathological one.

I’ve talked enough.