On 10/12/06, Jan Algermissen <[EMAIL PROTECTED]> wrote: > > > > > > > > On Dec 10, 2006, at 8:31 PM, Steve Jones wrote: > > > On 10/12/06, Jan Algermissen <[EMAIL PROTECTED]> wrote: > >> On Dec 10, 2006, at 2:45 PM, Steve Jones wrote: > >> > >>> how do I formally define > >>> a contract for REST that is machine readable. > >> > >> You don't (because you do not need to). > > > > No I really do... that is why I'm asking. > > No, you don't. That is a constraint of REST.
No I do... if you are saying that it is impossible to have formal contracts in REST and that REST cannot publish application interfaces ahead of time, this is against 30 years of R&D in distributed systems... And of course its exactly what Amazon do to help people use their REST APIs (http://docs.amazonwebservices.com/AmazonHistoricalPricing/2005-10-19/) > > > > >> > >> - the interface is uniform > > > > Nope, the INVOCATION is uniform, there is a big difference between > > this and the application interface. > > The application interface (repeat after me: the application > interface!!!!!!!!!!!! (doh :-) ) is ***UNIFORM***. > The INVOCATIONS are PUT,GET,POST and DELETE, etc. (at least for HTTP). Repeat after me.... NO IT ISN'T. That is the INVOCATION > > HTTP is an application protocol - try to accept it for a second and > see what happens. > (I myself only understood it much later than simply accepting it as > given). I want to place an order, this means I have to PUT the order, this means I need to know what the FORMAT of the order is that I'm allowed to PUT. So the application interface is PUT + Schema, now an order may result in a confirmation being returned that includes delivery dates, or indeed might include cost of delivery, this means I need the RETURN type of the request. Now I need to confirm the order with the shipping cost and add payment, this could mean PUTting the order again, this time with credit card details, or it might mean PUTting the order, then taking the returned simple ID and using that on a credit card "resource" and POSTing the credit card information to accept payment. So in order for a consumer to understand how to place an order I need to have a bunch of URIs and a bunch of Schemas that correspond to each of the requests. Without those URIs and Schemas being known it is NOT POSSIBLE for a consumer to understand how the system works. The fact that it uses PUT/GET/etc is the most minor part of the puzzle. As per http://docs.amazonwebservices.com/AmazonHistoricalPricing/2005-10-19/ > > > > >> - the behaviour (the state machine) is dynamically 'chosen' by the > >> server at runtime > > > > So its not something that consumer can rely on? > > EXACTLY!!! Think about what you rely on when you interact with > Amazon. Do > you expect the same sequence of pages every time? Or do you simply > not care? > (Because you do not need to care). Have you studied user experience at all? The concept that efficient systems are repeatable? So what you are saying is that it is IMPOSSIBLE to blackbox test a REST service? (hint: yes you are). And as I've said before, when Amazon start shipping things to me before accepting payment then you've got a point. And when they remove their API documentation (e.g. http://docs.amazonwebservices.com/AmazonHistoricalPricing/2005-10-19/) > > > There is no way that > > a consumer can know the effect of a call before it is made? > > HTTP defines the effect of the methods - there just aren't any > further application > interface semantics than these. Oh boy, please tell me that you are kidding. Amazon appear to thing that more is needed. > > > There is > > no way a consumer can know WHAT to POST to the server in what format > > The server sends you a form upon some initial GET (see APPs service > doc), > the form tells you what you can POST and where to POST it. So in other words you cannot design consumers ahead of time in a REST world? A bit odd that one, Amazon seem to disagree (e.g. http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=19) Can you tell me what the STANDARD format is for this "tells you" is? > > Forms are an essential part of REST; they enable parameterized state > transitions > (and enable the server to tell the parameters to the client at runtime). > Client and server must of course share the knowledge about the > parameters. Ahhh so much in so little a sentence.... yes of course they must share this... that is what I am asking... HOW do they share this information? Amazon have quite a bit of documentation (http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=19) but that isn't in a simple to consume format IMO. > > > and what the response format will be ahead of time? > > No (besides hints). The server will tell you what it is in the response. So its untestable... genius. So those Amazon things aren't REST as they tell me the format of the request and the response? > > > > > Somehow I doubt that. > > Try to accept it, THAT is REST. It is part of the essentials of the > "hypermedia as engine of application state" constraint (The hardest one > to grok - IMO). So Amazon's "REST" stuff isn't REST? I've definitely learnt something today. > > > > > > >> - the semantics of state traversals and resource state > >> representations is standardized > >> and needs to be known by the participating parties. That is what > >> MIME types do. > > > > I've been reading quite a bit on REST and MIME types and I've yet to > > find something that actually has meaning described in a standardised > > way. > > What kind of meaning are you looking for? Reat rhe Atom Pub protocol - > it is full of this stuff (e.g. the edit and edit-media link relation) I have read it, it tells me the format of the ENVELOPE, it doesn't tell me the meaning of the CONTENT. > > > If I have an invoice and it has > > > > <customer ref="http://foo.bar.com/customer/324234"; /> then it is the > > schema of invoice that describes the meaning > > no, the schema just defines syntax - you need more - a MIME type Examples would be nice.... > > > not app/xml (or whatever) > > app/xml is a bad example, because it is a meningless mime type. > UBL for example *should* have a mime type - unfortunately it does not. > (But if enough people want it.....) So give me examples of MIME types that are useful. > > > as a MIME type. > > > > MIME types do not standardise either the representation OR the meaning > > of a traversal, > > Sorry, but they do precisely this, nothing else. Example? > > > they just say the FORM (syntax) of the traversal, it > > is the source schema that helps to provide the meaning, and the > > destination that provides the schema, so I'm guessing that > > > > <customer ref="http://foo.bar.com/customer/324234"; > > schema="http://foo.bar.com/customer.xsd"; /> would be okay in REST? > > It is not really related to "okay in REST". What is important is that > the MIME type > (besides representing invoices) provides link semantics (including > form mechanism) that > allow the server to say stuff like "here is where you POST the > invoice to have it approved". What is the standard MIME type for an Invoice? The official list (http://www.iana.org/assignments/media-types/) is "oddly" missing it. I'm struggling to find any real world examples that match what you are saying. > > Try this: Do a purchase of a book on Amazon and keep track of based > on what decision you > click on what link and fill out what form with what values. Then > think about what a mime type > would need to carry out the conversation (== proceed through the > state machine) between two > software agents. The mime type would need to make up for all the > stuff you as a human can > figure out with your brain. (There is no magic). To do that in a MIME type seems pretty much like magic to me at the moment. It would need to be a very complex object. The example you give is trivial, try that with vendor managed inventory in a complex supply chain and I'm really struggling. > > (Amazon's purchase application is the 'application' in terms of REST. > The application tells the > client what options there are to proceed through it and the client > does so by traversing > hypermedia links sent to it by the server. > "Hypermedia as the engine of application state". And let me guess its the magic MIME type that gives the "meaning" of the traversal... I can't believe the OWL and RDF folks have missed that MIME has everything they need.... or maybe its not them that is missing something? > > (The benefitis: the server can change the state machine even while > you proceed through it) > (It is not specified at design time) > > As a second step think about how much it would take to generalize the > mime type you just > sketched and if you could form a group of people to create a > "purchase" media type that "could" excellent... so what you are saying is that we need to create a full ontology of MIME types to represent all possible meanings in order for this to work. Why can't we just do what Amazon did and publish the APIs? That seems much simpler to me. > is usable for more than Amazon. If it isn;t too complex (meets the > 80/20 point) and is > properly extensible (for those who need the 20% specifics) chances > are pretty good that > people will adopt it - let network effects do the rest. > > No, this might seem unsuitable for an enterprise context, but I have > come to think that it > allows for a very flexible (since decentralized) apporach, especially > if you are otherwise > in need for massive coordination (department-department, B2B or B2C). Creating a standards body, because it would need to be done that way for enterprise software, that defines a full ontology of MIME types for all possible meanings seems massive overkill, publishing an API and RDF/OWL (but please god lets get that stuff away from academics) is a proven technique that works. Why build yet another wheel to solve a problem with a solution? Why not just formalise the REST documentation set, take what Amazon have done, and other REST based APIs, and formalise it into a standard way of documenting how things should work? > > Jan > > > > >> > >> Jan > >> > > > > > > > > Yahoo! Groups Links > > > > > > [EMAIL PROTECTED] > > > >
