Re: How much REST should your Web API get?

Regarding "service document": what if I called it "home page" or "home
document" - would it make a difference? The problem with the classic
"service document" is that it, in the SOAP world, includes type information
and is meant for static "development time" binding. That is not the case
here: our "home document" only includes links with link-rels and a short
description.

Speaking about shared types ... Jimmy Bogard has a fresh blog post on this
issue: http://lostechies.com/jimmybogard/2013/05/01/messages-data-and-types/

The home document can be served as either one large JSON object with keys
as link-rels and values as URLs (like HAL does it), HTML with <a href="..."
rel="..."> or a homegrown XML format. Today I would probably have chosen
something like JSON-home (
http://tools.ietf.org/html/draft-nottingham-json-home-02), HAL or another
hyper media enabled *standard* JSON media type.

So, no, I do not think using a service document / home page disqualifies
the service as being RESTful - as long as it is used for late binding at
runtime (something which we make quite explicit in the documentation).

> albeit probably at the cost of a lot of initial tooling

Well, yes, some, but any client that understands JSON can do hyper media
with something like HAL. The server is based on OpenRasta which also has
nice support for creating links.

> Also, just curious, are you using your own custom media type or just
JSON/XML/other,

We have a custom media type "application/vendor.cbrain.casefiole+xml". I
still have to decide whether I prefer generic media types over custom media
types - in this case we chose a custom media type to get some experience. I
will write a piece on that later - when I have made up my mind about what I
think about it.

> 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?

Yes, I have also had problems with that :-) But take my example from the
previous post: the client and server does NOT share any kind of internal
type knowledge about what is behind that resource - actually that would be
a hopeless feat because the code base behind it is rather convoluted. What
they share is an understanding of the message format - the
public-stable-well defined-optimized for easy understanding by third party
devs-format. When we change the actual implementation type behind the
resource we do not change the external format. So servers and clients share
message format - not implementation type - and the clients and servers are
free to choose what ever internal types they want for representing it.

In the case of <img> resources: the shared message contract is the
jpg/gif/... format (media type). There is no shared understanding of the
server side data/type from which the image was created.

This mail was written with a 1 year old kid on my arm, so sorry for
misspellings ... I have to leave now :-)

Regards,, Jørn



On Fri, May 3, 2013 at 11:41 PM, Mike Schinkel <[email protected]> wrote:

> 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<http://roy.gbiv.com/untangled/2008/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
>