On Dec 11, 2006, at 10:39 AM, Steve Jones wrote: > 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,
No it isn't, because there is no coupling on the Schema. It may change dynamically. > 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. The return values are all fixed: 200,201,202.... (the API is uniform) > > 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 No! There are no return values - never. The server might send back some hypermedia for you to know what the next transitions are or where to check for the state of certain resources. > 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. No. You need one initial URI and the mime types must define the semantics needed for the client to find the other URIs. (Or do you know all URIs of an Amazon purchase up front?) > Without those URIs and Schemas being known it is NOT > POSSIBLE for a consumer to understand how the system works. All you need is the initial URI and the mime types (what you call "schemas"). > > The fact that it uses PUT/GET/etc is the most minor part of the > puzzle. Minor - in what sense? > > As per http://docs.amazonwebservices.com/AmazonHistoricalPricing/ > 2005-10-19/ > > Only took a close look, but from what I see, there are three independent services that simply provide search operations (they let you index into the set of items). The prose defines three forms without any standardized means and the described return formats are also not standard (as for example Atom would be). If you program a client against these services, you couple it to this single form/response schema - not a good idea. Both, the form and the response should be standardized (e.g. OpenSearch). >> >>> >>>> - 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). No, you somehow do not get your brain rewired to realize that the sequence of operations is not known at design time. That rewiring took me about two years I think, so... You can blackbox tet an APP server for example. > > 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. Frankly: who cares what Amazon thinks? Besides, what is that 'more' they think 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? Sure you can. You just need to built-into the consumer the understanding of how the server tells it what and where (and when) to POST. > 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? The mime types..... > >> >> 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? Via standardized mime types (the awareness of which you need to build into the components. Seems you are getting closer. > 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. It is also not standardized. > >> >>> 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? Well, if you write a client to rely on such design time information, *then* you are breaking REST. Of course you'd need a hint of what mime type (s) to expect (because you need to build awareness of it/them into your client) but the only athoritative information about the type of representation you actually receive is in 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. Strictly speaking, no. The way to improve it would be to use OpenSearch and Atom/RSS, hell, even HTML <li> would be better. OTH, it is part of REST's strengths that Amazon can throw this out (the uniform interface lets us access it, download it and the discuss it) and maybe others pick it up because it makes sense to them. If enough people do - maybe there'll be a new standard. Clearly this is a Web-targetted way of evolution, but IMHO, enterprise IT can benefit from this approach (being a contrary to all-defined-up-front systems). > > >> >>> >>> >>>> - 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. Right, because you do not need to know for the purpose of APP. > >> >>> 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.... We'll get to those... > >> >>> 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? HTML....? > >> >>> 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. Right. So what? Where is the standard API for order processing? > > I'm struggling to find any real world examples that match what you > are saying. We are just starting, unfortunately (or luckily?) there is no big industry behind REST that would drive this process. I need to evaluate UBL for this, just did not have the time. > >> >> 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. So, the API's you'd need would be any simpler? I am amazed that people think that designing APIs is simpler than designing hypermedia types. Not to speak of evolving them. So, why are you not struggeling with doing the inventory thing with an API? > >> >> (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? What do you mean? Can you explain? > >> >> (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. not all possible meanings, but Mime types for the things you want to get done, yes. Much like you'd need APis otherwise. > > Why can't we just do what Amazon did and publish the APIs? That seems > much simpler to me. And simpler to evolve, extend and maintain? The first client that programs against Amazons interface make it impossible to evolve it without breaking the client. Now if formats were chosen that had defined clear extensibility strategies (e.g. Atom) that would be a differnt game. > >> 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, Well, you can do this within your system boundaries, standardized does not really mean globally standardized. > 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? Good idea. Jan > >> >> Jan >> >>> >>>> >>>> Jan >>>> >>> >>> >>> >>> Yahoo! Groups Links >>> >>> >>> [EMAIL PROTECTED] >>> >> >> > >
