Re: How much REST should your Web API get?

On May 3, 2013, at 3:57 PM, Jørn Wildt <[email protected]> wrote:
> We decided to go "full monty" and stick as closely as possible to the REST constraints - especially hyper media. This means our clients have one, and only one, single entry point to the REST service - and that entry point contains a service document with links/link-rels to all top level resources. 
> ...
> 
> This too was easy using hyper media...
> 
> The last happy moment also illustrates what (I think) was meant by "A REST API should never have “typed” resources that are significant to the client" in Roy's famous rant "REST APIs must be hypertext-driven". Had the client known anything about the internal type behind the facade then it would have failed when we introduced multiple types behind the facade.
> 

Not to diminish what you've accomplished, because it sounds like it works extremely well in practice albeit probably at the cost of a lot of initial tooling but I would question if the use of a "service document" does not by-definition disqualify it as being RESTful as per Roy's precise definition, ironically stated in the blog post rant you reference.

As I understand it from a recent multiple re-reading of Roy's infamous rant the use of a service document would mean individual messages are indeed not fully description and that would disqualify it as being "RESTful."  Not that I disagree with the concept of a lightweight JSON-based service document that simply points out all the URLs; frankly I rather like the idea. But unless I mis-read or Roy has revised his definition of REST since that post I think service documents do not a RESTful web service make?

Also, just curious, are you using your own custom media type or just JSON/XML/other, and if not the former does that also not disqualify it from being considered RESTful?  If you are using your own custom media type I'd be curious what the media type is, i.e. what is "xxxx-yyyy" for "application/"xxxx-yyyy" and what it's base format is; XML, JSON, HAL, ATOM, etc?

The one thing I still have not been able to fully understand from Roy's rant was just exactly what he meant means by a "typed" resource?  Doesn't a <img> tag imply a resource of type JPEG, GIF or PNG, for example?  So I have never been fully able to grok that part.  Any clarifications from anyone?

-Mike