RE: Issue 5; GET vs GetLastTradePrice

+1

Google is a great example.

http://www.google.com/search?as_q=mark+baker&num=10&hl=en&ie=UTF-8&oe=UTF-8&btnG=Google+Search&as_epq=&as_oq=&as_eq=&lr=&as_ft=i&as_filetype=&as_qdr=m3&as_occt=title&as_dt=i&as_sitesearch=&safe=active

There are a few questions that a programmer would ask when presented with 
this URI reference to the Google Search service:

1) What are the query parameters (and any constraints on the values of 
these parameters) to this service? 
2) What am I going to get in response to retrieving the/a representation 
of the resource that is implied by this URI? Or,
put another way; what manner of representations of the resource 
implied/identified by this URI are supported?

In short, what is the interface to this service. Sure, there are many more 
questions related to semantics, etc.
that are also interesting, but let's focus on these for starters.

In some cases, you might say that the answer to question #1 above is 
irrelevant. True, there are classes of application
for which the answer to that question is unnecessary. They will merely 
dereference the URI given to them. However, there are classes
of application for which the answer to #1 is quite interesting, if not 
critical. If I am developing a client/consumer of this
service, then clearly the answer to #1 is needed so I can populate the 
query parameters correctly. Ideally, this description would 
be in some machine readable and standardized and interoperable form that 
will allow us to develop tools that can process this 
information and generate some of the code. On the Web today, we have HTML 
forms and soon we may have XForms to
aide in this aspect. These involve a USER INTERFACE and HUMAN INTELLEGENCE 
to understand the semantics of
the interface so that the query parameters can be effectively and 
correctly populated to effect the appropriate request. Whether
the resulting request is POSTed or URLencoded into a GET on a URI is 
largely a difference of serialization of the request.
To suggest that the HTML form is not a specialized interface in such a 
case is nonsensical. It is most certainly an aspect
of the interface to the resource that is identified by the part of the URI 
preceding the '?' separator.

As for #2, there are classes of applications for which the answer to this 
is quite interesting, if not critical to know at 
design time. Sure, not all classes of application will have need to know 
the answer. Some consumers/clients will be written
to handle anything thrown at them, like today's browsers. When a new 
standardized media type is specified, they'll 
just add a module that handles that media type. However, as we start to 
deal with specific vocabularies that address
domain specific semantics (beyond rendering for human consumption) the 
descriptive aspect missing from REST and
HTTP alone become increasingly important.

I don't want to hear anything about custom interfaces. Whether you like it 
or not, in the case of Google and any other
form-based service on the Web, there is a custom interface. Sure, it is 
layered on top of the generic, uniform
interface of the Web and HTTP, but it is still custom none the less. Using 
URL encoding of form parameters allows one to take
advantage of the Web infrastructure, but it doesn't change the fact that 
there is a custom interface involved.

Again, there is little argument that using HTTP GET with the above URI 
will provide some benefits over use of 
a POST of the same arguments (caching, bookmarking, etc.). Whether a POST 
includes some indication as to 
the "method" is irrelevant. As I am sure that you will note from the query 
above, there is actually a "method" of sorts encoded
into the URI reference's query parameters (this URI reference uses the 
Advanced Search "method" which takes a different
set of arguments than the simple/standard search "method" available at the 
same address of http://www.google.com/search).
I am not a big fan of the RPC style use of Web services myself, but some 
find it more accessible and that it maps
fairly straight-forwardly to existing code, which for some is important. 
Over time, I believe that that style of usage will
wane in favor of a more document-oriented style which I personally believe 
will prove to be a superior solution in
the long run.

What I believe is at issue is; how can we encode enough information in a 
description such that we can
leverage the benefits of GET when appropriate. How can we encode a 
description of a reference to a
Web service? A URI alone is inadequate, IMHO.

Let's consider Mark's original example of the invoice containing URI 
references to items.

<invoice>
  <item productid="http://someco.example.org/product/439843434"/>
  <item productid="http://someco.example.org/product/348787492"/>
  ...
</invoice>

Hmmm... I have no clue as to what the answer to #2 above is for this 
particular example.
Wouldn't it be nice if I had some clue as to what manner of thingy I'll 
get, or can get,
if I dereference these URIs? I suppose I could dereference one of them and 
see what I get,
and then write my code that will process the information. Will I have any 
certainty that 
dereferencing the other URI will result in the same type of returned 
representation? They are
after all different resources aren't they? Just because the URIs have the 
word "product" in
their path means nothing to me because a URI is meant to be opaque to all 
but the authority
that assigned the URI to the resource. The fact that I happened to find 
the URI in the productid attribute of
an invoice tells me nothing either, really.

Of course, I will probably want to write my software to process the 
invoice and its related
information before I actually get an invoice to process... Maybe you and I 
are writing the client and
service concurrently. So, let's assume that the service provider has 
generated a schema for the 
invoice:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault
="qualified">
        <xs:element name="invoice">
                <xs:complexType>
                        <xs:sequence>
                                <xs:element name="item" type="itemType" 
maxOccurs="unbounded"/>
                        </xs:sequence>
                </xs:complexType>
        </xs:element>
        <xs:complexType name="itemType">
                <xs:attribute name="productid" type="xs:anyURI" use="
required"/>
        </xs:complexType>
</xs:schema>

This is all well and good, but unfortunately, there still isn't enough 
information to go
on w/r/t the productid URI. A type of xs:anyURI is IMO simply inadequate. 
What we really want to have
here (IMO) is a typed reference that indicates that the value of the 
productid attribute
is a URI that references/identifies a resource that is a product, I 
believe we want to be able to give some
clue as to what the properties of a product resource are and what 
representations might be
available so that we can develop software that can process this 
information should the 
URI value of a productid attribute be dereferenced. I may even want to be 
able to constrain
the value space of the productid attribute to be a reference to a product 
resource.

Of course, this is just addressing GET. What about POST? Let's just assume 
for a moment
that the product resource class supports the POST HTTP method. Hmmm... 
where do I find out
what entity to POST to it? And what does POST mean for this resource? 
RFC2616 suggests that POST is a uniform
method to accomodate a wide variety of uses.

So, POST could be used for just about anything. The mere fact that a 
resource supports the POST method
really tells me nothing. Let us assume for a moment that the product 
resource supports POST for two purposes:
        Annotation (Customers can POST a product review saying how 
wonderful (or crappy) the product is in their opinion)
        Modification (the owner can update the availability of the 
product, without having to retrieve and replace the entire product object
                using a GET/PUT)

The determination of the intent or purpose of the POST method is based on 
a processing of the entity. Whether it is
based on the content-type or on some computed value based on parsing the 
entity is IMO largely irrelevant. However, 
wouldn't it be nice if there were some standardized, machine processable 
means of describing what manner of entity/message
body was required for each intent?

Cheers,

Christopher Ferris
Architect, Emerging e-business Industry Architecture
email: chrisfer@us.ibm.com
phone: +1 508 234 3624

Mike Champion wrote on 01/02/2003 09:53:46 AM:

> 
> 
> 
> > -----Original Message-----
> > From: Walden Mathews [mailto:waldenm@optonline.net]
> > Sent: Thursday, January 02, 2003 9:25 AM
> > To: Newcomer, Eric
> > Cc: www-ws-arch@w3.org
> > Subject: Re: Issue 5; GET vs GetLastTradePrice
> > 
> >
> 
> > If I dereference a "service name" and get a body of 
> > description on how to access that service, isn't
> > that body still describing, at the end of the day, some 
> > syntax and some semantics? 
> 
> Sure.  SOAP and WSDL aren't solving the world's problems, they are 
basically
> just removing some of the mechanical impediments to describing and 
invoking
> object interfaces across platforms, languages, vendors, etc. Just as the
> hypertext Web generally works because there is an intelligent human 
reading
> the rendered HTML, SOAP and WSDL work because there are intelligent 
humans
> doing the mapping from the syntax level they describe to the semantics 
of
> the underlying code.
> 
> 
> > Isn't the need for "custom coding" a function of custom 
> > interfaces, not the lack  of descriptive
> > material about custom interfaces? 
> 
> I'm not sure what you're getting at, FWIW.  The big advantage of WSDL, 
IMHO,
> is that it allows the generation of the code to generate the SOAP 
messages
> and programming language classes to handle them.  That's clearly the 
selling
> point for  something like the Google web service, which is much more 
complex
> under the covers than a simple GET invocation of a URI with a query 
encoded
> in it, but is simpler in practice for the legions of VisualStudio.NET 
(etc.)
> programmers who can auto-generate a class that queries Google. 
> 
> If there is one example that I wish the REST advocates here would study
> carefully, it's Google -- for better or worse (and I personally think 
for
> worse!) the world was lured into reliance on a fragile, suboptimal, 
overly
> complex interface simply because the code is generated "by magic" from a
> WSDL description.  There's no reason that some future version of WSDL 
that
> supports SOAP 1.2 couldn't allow us the best of both worlds -- the
> robustness of a RESTful interface and the convenience of push-button 
code
> generation. As I said in my last message in this thread, it's the TOOL
> VENDORS, not the WSA, RESTifarians have to convince to support this 
stuff.
> 
>