On Oct 18, 2010, at 9:14 PM, Bram de Kruijff wrote: > Hi all, > > 2010/10/18 Marcel Offermans <marcel.offermans at luminis.nl>: >> As further input to the discussion, Rickard posted a follow up: >> http://www.jroller.com/rickard/entry/rest_and_the_missing_link >> Summing that one up in one sentence, he stresses the importance of having >> proper links, which can be used to discover what you can do, and that in >> such a way that they are fairly resistant to change. > > I think I like it in the sense that it seems to make the contract a > little less brittle. However I'm not sure it is realy worth the extra > request. Wat are the advantages? > > For one, the client only has to hardcode the base resource URI and > below that the serverside is able to refactor (eg. change path) > without the client code breaking. Still, there is one hardcoded path > and a new need for hardcoded metadata identifying what uri references > the "possibleEntities" link. So what did we gain?
The main benefit of using explicit links in your data is that you can freely shuffle links around if you need to. All you need to know is that an entity you find at some location has a given 'close' method, and behind this link, you find a form that instructs you how to use it. Think of it as a function prototype: if the call will fail because there is a new parameter that needs to be set, you will know _before_ trying to invoke it, instead of afterward. This prevents a situation in which you blindly POST (or --gasp-- GET) data to some endpoint, and get a non-instructive 40X back. Yet, I do agree that we should not move to a situation in which we redo SOAP. > > Second, the server could decide to hide the "possibleEntities" because > the user is not authorized to access it. But actually throwing a 401 > response (leverage HTTP!) from the query resource would give the > client the same info and you need that anyway. Ok in this case we have > possibly saved us a couple of request but I guess the question if that > is worth is depends on the domain and how much this situations occurs. > Again, do we realy gain much? > > Concluding, I think I like it as a model and way of thinking about a > REST api but it is not exactly a silver bullet in REST design :) Or am > I missing something? You're definitely right that this is not the silver bullet of REST API design, and it will only be applicable to some parts of the actual API. > ---snip--- > >> I believe this can be very well wrapped around the OSGi service we have for >> those already, but we should come up with a uniform 'shape' of the types of >> services we use for that. Thinking along those lines, it seems that the >> services that are less suited for wrapping (e.g. persistence) are more >> infrastructure services, so should not be exposed at all. >> >> That leads to the question: if, from a design point of view, it's not >> appropriate to expose these using REST, then how should we expose them? I >> don't think "not at all" should be taken too literal, so: >> 1) do we simply expose them as a service, using remote services when >> necessary >> 2) do we go fo the "accessible over HTTP" option (which is not REST) >> 3) do we force the lipstick on the chicken and try to do it with REST anyway >> This is a fundamental discussion, since up til now we've mostly stated >> "everything is connected via REST". > > My thoughts (at this point) on that point: > > 1) In the case of applications / point solutions identify the > "Business Interface" and plug that into our REST framework. > 2) In the case of infrastructural (foundation) services think very > hard. Do we realy need a RESTfull API on top of cassandra or will > every application just access it at the OSGi service level? ... and > what about BlobStore? Or do we allow case by case custom HTTP > protocols? Hmmm :S > 3) In the case of "internal" remote services don't worry about it.,,, > implementation detail > > >> There are a number of open questions that we need to answer before we can >> start happily wrapping our services. For instance, what about user- or role >> dependent resources, like '/gadgets/mine'? What does 'logging in' mean in >> this context? Do you post to '/session/create', and get back a session which >> you can use to find 'your' stuff, or should all services be user-aware? And >> tenant-aware? And application-aware? >> >> Interesting questions indeed. Sessions (for holding on to state) at first >> don't seem to fit in the REST model. However, if you model them with REST >> they just become resources, so that actually sounds like a good way to >> approach it. > > +1 > >> Logging in is an interesting one. I think this should be done by navigating >> links too. > > No serverside (conversational) state, thus authenticate every time at > the HTTP layer (basic auth over a SSL/TLS wire). > >> I agree we need to do some designing before we start coding here. A good >> approach would be to take some of our use cases and define how the REST >> calls would look like in each step. > > Agreed, RESTfull design is a tough cookie and we need some experience. > Maybe start with making the APIs used (or in development) by existing > projects explicit and evaluating them on RESTfullness? > > IMHO one important thing to keep in mind constantly is that REST > intends to leverage HTTP (not just use it as a wire like WS-* or "fill > in one of your custom querystring based RPC style protocol here"). So > when thinking about authentication, caching, content negatiation etc > look at HTTP first. I agree that we should try to stick to something that actually is representational state transfer, but the main question we need to get answered is, what do we want to gain by using REST? All services, or do we focus on delivering (cachable) content? Do we assume that we are the only web application that uses our protocol (from some part of Javascript), or do we want to expose our services to third party clients? I feel I pose more questions than answers on this list :) Angelo
