Re: How much REST should your Web API get?

> We have a custom media type "application/vendor.cbrain.casefiole+xml"

Sorry, I was too quick here. The REST service is actually composed of two
different sets of resources that mixes various parts of the system. Half of
it is in "application/json" (the mobile part) - and half of it is in
"application/vendor.cbrain.casefiole+xml" (the part designed for systems
integration with third party vendors).

As I said: I have yet to make up my mind w.r.t. custom versus generic media
types.

/Jørn


On Sat, May 4, 2013 at 8:28 AM, Jørn Wildt <[email protected]> wrote:

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