Re: [rest-discuss] How much REST should your Web API get?
- On May 3, 2013, at 3:57 PM, Jørn Wildt <jw@...> 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
- Once again you have given me much to ponder. Thanks for the effort; I will be trying to internalize this.
On May 4, 2013, at 1:49 PM, "Markus Lanthaler" <markus.lanthaler@...> wrote:
> On Saturday, May 04, 2013 7:03 PM, Mike Schinkel wrote:
>> Hmm. Okay, the more I think I understand about REST the more I think
>> I don't understand and/or am unsure who actually really understands
>> REST besides Roy.
>> As I've read Roy I've come away understanding that messages must be
> No, you are confusing self-contained with self-descriptive.
>> and the only thing the client should know is how the
>> links in the returned representation are defined to behave as defined
>> by the representation's content yype. Having links in one document and
>> data in a second document where you have to have the contents of both
>> documents seems to me to violate that need for self-containment.
> ... if there would be a self-containment constraint that would be true --
> but there isn't.
>> I do have one question; if there is a home document that is cacheable
>> for some period "X" and at the time immediately after an API client
>> retrieves the home document the servers are moved and the client later
>> perform an operation that requires URLs from the home document but
>> before "X" time has passed, it can cause failure. If the message is
>> self-contained that time window is greatly reduced. This is one of the
>> reasons I can postulate there is a need for self-contained messages.
> That doesn't matter at all. Program defensively, detect the error, and
> I could just as well argue that separating them allows you to request them
> in parallel which would probably be faster so the time window you are
> talking about would be reduced even further.
> Markus Lanthaler