Re: [rest-discuss] How much REST should your Web API get?
- On May 4, 2013, at 2:28 AM, Jørn Wildt <jw@...> 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.I'm aware the baggage the term "service document" has with many people because of the weight of such things in the SOAP world and elsewhere, but that's not why I was questioning it.Instead I was mhyself considering a very similar concept where a "home document" as you are restyling it could be used to contain URI templates that map to rel values, etc. But from how I read Roy's comments I came to the understanding that the separation of message from a "roadmap document" (there, a neutral term?) was not RESTful. From , to whit (emphasis mine):A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand)....The interface doesn’t need to be discovered. It is defined right there in the hypertext. The representation tells the client how to compose all transitions to the next application state. This could be as simple as an anchor or as complex as a java applet. For example, Day’s CQ5 content management system allows the user to perform direct image masking and manipulation on the client side and save the filtered image view as a new resource, all within the environment of a standard Web browser window.And then from :Within REST, intermediary components can actively transform the content of messages because the messages are self-descriptive and their semantics are visible to intermediaries.So what I'm getting at his is that if your client needs to first download your roadmap document to know which URLs your individual messages reference then it is stateful and while it is (probably) hypermedia it seems is not RESTful (because we know that Roy says REST is all or nothing.) No?I'm not saying that your approach might not be better than pure REST for your use-case, but the more I try to truly understand REST the more it seems that *nobody* it really doing APIs that are purely RESTful (yes, I'm using the superlative "nobody" on purpose.)If nobody's APIs are actually fully RESTful then who's to say if one person's tradeoffs are better than anothers? Until most everyone can agree on what is and is not RESTful it seems that too many people are talking past one another and claiming to be "More RESTful than thou" (note the religious allegory? BTW, I'm not singling out you with this comment; I mean everyone, including me.)Frankly I wish Roy were interested in jumping into these conversations to clarify for others benefit but I completely respective his evident desire not to spend his time doing so.Thanks. Also looking for more stuff like this.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.Nice, I will be reading that too. Good to see Mark's efforts here; I really do think of him as one of the best web architectures out there.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).Although I can see the benefits of a home document my reading of Roy still tells me that use of such a home document would not be considered RESTful. It would be instructive to know what others think especially since we are unlikely to hear from Roy on the subject.We have a custom media type "application/vendor.cbrain.casefiole+xml".Cool.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.Reading Roy on the subject I think he is clear that media types *must* be non-generic for an API to be RESTful, no? IOW, it's effectively not possible to use "applications/json" as the specified media type for a web service unless the web service is really, really trivial. Again, from Roy with my emphasis:In terms of testing a specification, the hardest part is identifying when a RESTful protocol is actually dependent on out-of-band information or if the authors are just overspecifying things for the purpose of documentation. What I look for are requirements on processing behavior that are defined outside of the media type specification. One of the easiest ways to see that is when a protocol calls for the use of a generic media type (like application/xml or application/json) and then requires that it be processed in a way that is special to the protocol/API. If they are keying off of something unique within the content (like an XML namespace declaration that extends the semantics of a generic type), then it’s okay. Usually, however, what they do is assume that the response has a specific structure beyond that defined by the media type. When the structure changes, the client will break.Doesn't this mean effectively that without a specific media type it cannot be RESTful?Also there's also this from :The media type is a generic processing model that every agent can learn if there aren’t too many of them (hence the need for standards).To me that say that REST is most useful for systems that are deployed on a broad scale where many different people/systems are using a common/shared media type, for example "text/html" or whatever HTML5 calls it these days. :) Which makes me question if all the effort towards building RESTful system in-the-small is really not missing the point? Again, from  (emphasis mine):and/or across industries as was implied here.
It seems to me the most useful thing the REST community could do for the web of APIs in general is to focus on the establishment of a small number of well-known media types that can be used withinREST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).> 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?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.Ah, that was helpful. Thanks.This mail was written with a 1 year old kid on my arm, so sorry for misspellings ... I have to leave now :-)Belated congrats there. :)-Mikehttp://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
- 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