Assuming this group is still alive (I know everybody's been busy
evangelizing in W3C lists), I have a followup question on the
purchase order scenarios.

There is a standard function in an ERP system called Available to
Promise, or ATP for short.

"Available" means "not already promised to somebody".

It is used to decide if a purchase order can be fulfilled or not.
It is usually used for purchase orders for products, so that is what
I will describe here.

There are a variety of APIs and algorithms, but they boil down to two
main queries, which I will describe in plain English, not code:

1.  How much of a product is available to promise at a future time?
For example, how many blue shoes can I get by tomorrow?
The answer is a quantity.

2. Is a specified quantity of a product at a specified time?
For example, can I get 100 blue shoes tomorrow?
The answer is a boolean.

This query might be offered to a customer to use before they place an
order, or it might be used by the order-taking Web resource before
accepting an order.

In REST terms, I assume this is a GET with parameters, and the Web
resource to address is the Product (i.e. BlueShoe).

How would you say it?

Thanks,
Bob Haugen

Interesting.

The URI (path+query) would point to the answer you want to give, having the
'path only' point to the product is neato, but not required.

To get the availability:
http://www.myinventory.foo/products/blueshoes/availability/?when=tomorrow

To get the threshold (more than 100)
http://www.myinventory.foo/products/blueshoes/availability/?when=tomorrow&ab
ove=100

But of course there are a million ways to slice it.
You can narrow down the choices based on whether PUT/DELETE/POST are needed
on the same resource - and they probably aren't. POST might be used to
allocate out of the availability - but a business document probably will
have that information & so you'd just submit it to the 'orders' collection &
let the values be updated via business logic (meaning that the values from
these two sample queries are 'synthetic' properties, derived from data
manipulated via other actions)


----- Original Message -----
From: "bhaugen32" <bhaugen32@...>
To: <rest-discuss@yahoogroups.com>
Sent: Thursday, April 04, 2002 10:42 AM
Subject: [rest-discuss] Restifying Available to Promise


> Assuming this group is still alive (I know everybody's been busy
> evangelizing in W3C lists), I have a followup question on the
> purchase order scenarios.
>
> There is a standard function in an ERP system called Available to
> Promise, or ATP for short.
>
> "Available" means "not already promised to somebody".
>
> It is used to decide if a purchase order can be fulfilled or not.
> It is usually used for purchase orders for products, so that is what
> I will describe here.
>
> There are a variety of APIs and algorithms, but they boil down to two
> main queries, which I will describe in plain English, not code:
>
> 1.  How much of a product is available to promise at a future time?
> For example, how many blue shoes can I get by tomorrow?
> The answer is a quantity.
>
> 2. Is a specified quantity of a product at a specified time?
> For example, can I get 100 blue shoes tomorrow?
> The answer is a boolean.
>
> This query might be offered to a customer to use before they place an
> order, or it might be used by the order-taking Web resource before
> accepting an order.
>
> In REST terms, I assume this is a GET with parameters, and the Web
> resource to address is the Product (i.e. BlueShoe).
>
> How would you say it?
>
> Thanks,
> Bob Haugen
>
>
>
> To unsubscribe from this group, send an email to:
> rest-discuss-unsubscribe@yahoogroups.com
>
>
>
> Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
>
>
>

"S. Mike Dierken" wrote:
>
> Interesting.
>
> The URI (path+query) would point to the answer you want to give,
having the
> 'path only' point to the product is neato, but not required.
>
> To get the availability:
> http://www.myinventory.foo/products/blueshoes/availability/?
when=tomorrow
>
> To get the threshold (more than 100)
> http://www.myinventory.foo/products/blueshoes/availability/?
when=tomorrow&ab
> ove=100

I like it!
Maybe just plain
http://www.myinventory.foo/products/blueshoes/availability
would present something like an MRP inquiry, starting with the blue
shoes on hand, followed by a list of scheduled receipts.

(That's the way an ATP report often looks.)

> But of course there are a million ways to slice it.
> You can narrow down the choices based on whether PUT/DELETE/POST
are needed
> on the same resource - and they probably aren't. POST might be used
to
> allocate out of the availability - but a business document probably
will
> have that information & so you'd just submit it to the 'orders'
collection &
> let the values be updated via business logic (meaning that the
values from
> these two sample queries are 'synthetic' properties, derived from
data
> manipulated via other actions)

I agree.  Allocation requires a business commitment from a customer,
usually in the form of an order.

Thanks, Mike.

-Bob Haugen

I had a good friend ask me about whether Model-View-Controller is a good
framework for building apps on a Java App Server.
This led me to thinking about how different people view the job of building
'web applications'.
I've always thought of MVC as useful way of building
single-user/single-machine apps - classical programming.
But I also see the separation of data, presentation and logic being very
important and used in multi-tier large-scale systems - the two are very
related.

The interesting part is that I think different audiences view 'the web' as
one of these three facets of a large system;
  - REST advocates view the Web as an information system - the 'model' part
  - majority of web app developers and web app tools (asp/jsp/etc.) view it
as user interface - the 'view' part
  - many soap developers view it as functional services - the 'controller'
part (sort of, i'm probably stretching the analogy here)

I think it is wonderful that the Web is rich enough to be viewed in these
different ways, but I see it as a wholistic blending of all these. Knowing
where other people are coming from can help in understanding each other and
in communicating with and educating each other.

In my view, the current crop of Web application development tools is overly
focused on user interface aspects.
When I see development tools and servers project 'MVC' as a good way to
build applications, it seems like they are looking from the server inward
and applying MVC, where I see the value in looking at the server outward and
applying MVC concepts. Design a system to separate data, presentation and
logic /outside/ the web server. This lets you build applications that span a
single server - whether clustered or not.

Another thought I had was to daydream about what a real REST oriented Web
server development environment would look like. I'm imagining a blend of a
RDBMS interface with HTTP/REST concepts - rather than saying "create table
users (userid int, email varchar(255))" we could say "create collection
users (userid uri)" or something. And we could easily build user interface
without putting the UI template in the URI. "when user-agent like mozilla%"
or "when accept like text/%" or something.

Mike

"S. Mike Dierken" wrote:
> I had a good friend ask me about whether Model-View-Controller is a
good
> framework for building apps on a Java App Server.
>  - REST advocates view the Web as an information system -
the 'model' part
>  - majority of web app developers and web app tools (asp/jsp/etc.)
view it
> as user interface - the 'view' part
>  - many soap developers view it as functional services -
the 'controller'
> part (sort of, i'm probably stretching the analogy here)

Alternatively, in REST:
'model' = resource
'view' = representation
'controller' = handler of GET, POST, PUT, DELETE, etc.

(I'm less sure of the controller.)

-Bob Haugen

bhaugen32 wrote:

> Alternatively, in REST:
> 'model' = resource
> 'view' = representation
> 'controller' = handler of GET, POST, PUT, DELETE, etc.

Right on the money, IMHO.

jb

I suppose everybody is tired of Yahoo groups
by now, but the REST gang doesn't seem to want
discussion on the Wiki, so I don't know where
else to post this question-for-discussion.

How much of the current kludges for session
state management could be avoided by making
session state(s) into Web resources?

Paul Prescod has hinted at this a couple of
times.

Here's an example of people struggling with
the issues without considering REST:
http://c2.com/cgi/wiki?DoesAnyoneActuallyUseStatefulSessionBean

Thanks,
Bob Haugen

> How much of the current kludges for session
> state management could be avoided by making
> session state(s) into Web resources?

> Thanks,
> Bob Haugen

I think there's a project to be done of working out a RESTy session
management protocol.  ...just have to sit down and do it, that's all.

- Lucas

bhaugen32 wrote:
>
>...
>
> How much of the current kludges for session
> state management could be avoided by making
> session state(s) into Web resources?

I tend not to think about session state as a thing. A client interacts
with a service and in so doing the service may create new resources.
They may be short or long-lived. Is there, in general, a requirement to
reify this as a "session"? Opinions requested.

One reason that I resist this is because I would like for it to be
possible to construct a single logical client from many different "HTTP
clients". i.e. for me to dispatch part of the job to a totally different
software component merely by sending it a URI. "Tax form verification
code service, please check my tax form before I send it. It is at
http:///". This gets much more complicated if the client and server have
a shared, implicit notion of where we are in the multi-step process.

One way it would help deal with the issues discussed on that c2.com wiki
is by spreading out the state among multiple resources so that you might
not need to load balance any particular resource. As the "state" is
spread among different URIs, each new step in the process can switch
machines if necessary. Still, the steps will often need to share
information so you still need to push this back to the database and that
will still be somewhat expensive.

  Paul Prescod

Paul Prescod wrote:
> bhaugen32 wrote:
> >
> >...
> >
> > How much of the current kludges for session
> > state management could be avoided by making
> > session state(s) into Web resources?
>
> I tend not to think about session state as a thing. A client
interacts
> with a service and in so doing the service may create new resources.
> They may be short or long-lived. Is there, in general, a
requirement to
> reify this as a "session"? Opinions requested.

No.  I wish I had not framed the question that way.
In fact, the reason I asked it was because you hinted in some
previous messages that the resources created by interactions would
eliminate the need to reify and keep track of "sessions".

To the extent that the idea holds up, it could also eliminate all
kinds of crufty buggy baggage.

> One reason that I resist this is because I would like for it to be
> possible to construct a single logical client from many
different "HTTP
> clients". i.e. for me to dispatch part of the job to a totally
different
> software component merely by sending it a URI. "Tax form
verification
> code service, please check my tax form before I send it. It is at
> http:///". This gets much more complicated if the client and server
have
> a shared, implicit notion of where we are in the multi-step process.

Unfortunately, business exchanges require trading partners to agree
on states, but they could be states of resources, not processes.
(Or to put it another way, the states of a business process can be
modeled as states of resources.)  For example, trading partners need
to know if an order has been accepted, rejected, fulfilled, etc. but
those are states of the order, and both the order and its state(s)
could be Web resources.

-Bob Haugen

P.S. Paul, I could search for the hints in previous messages if you
want me to, but maybe you remember them?  I didn't bookmark any of
them, unfortunately - a lightbulb went on when I was reading the Wiki
page and thinking you had the seed of a better way.

Hi,

I would like to see a document where you can learn REST by example.
For one reason, to understand it better and also because there is
growing interest in the Ruby community to consider using a REST
architecture as an alternative to a SOAP based approach. This document
would start with very simple examples and gradually evolve into more
complex situations (along with explanations why thing should be done
that way).
What would be good examples to start with? I was thinking about things
like 'hello world', a calculator, an addressbook, a simple chat program.
Is the REST wiki a good place to start such a document, or should I
put it on the Ruby wiki? (the document could have different versions
for other programming languages as well).
Any suggestions would be most welcome.

   Erik Terpstra.

Lucas Gonze wrote:
> I think there's a project to be done of working out a RESTy session
> management protocol.  ...just have to sit down and do it, that's
all.

What would be the simplest or most generally congenial environment
where a group could collaborate in some REST experiments?

> What would be good examples to start with? I was thinking about things
> like 'hello world', a calculator, an addressbook, a simple chat program.
The calculator might be a bad sample problem, because it doesn't show the
utility of REST - transferring the state of a calculator is unnecessary
because the state can be completely algorithmically regenerated on the
client. A 'shared calculator' might be interesting though.
The addressbook is a really good example - there is a wide range of
approaches, from simple ones to get the general feel and style of REST, and
some more complex ones that get into the tougher areas of collections,
nesting, multi-protocol linking, security, etc.
The chat might be better cast as discussion groups, since 'hot live chat'
isn't that common with pure HTTP (unless you use KnowNow technology.)

Another thing to think about is to avoid the 'browser == web' mentality that
throws people off the http trail. Toss XML around (without worring about
using 'industry standard schemas') and do some linking between things
(possibly between apps...).


> Is the REST wiki a good place to start such a document, or should I
> put it on the Ruby wiki? (the document could have different versions
> for other programming languages as well).
> Any suggestions would be most welcome.
>
>   Erik Terpstra.
>
>
>
> To unsubscribe from this group, send an email to:
> rest-discuss-unsubscribe@yahoogroups.com
>
>
>
> Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
>
>
>

Hi,

I would like to see a document where you can learn REST by example.
For one reason, to understand it better and also because there is
growing interest in the Ruby community to consider using a REST
architecture as an alternative to a SOAP based approach. This document
would start with very simple examples and gradually evolve into more
complex situations (along with explanations why thing should be done
that way).
What would be good examples to start with? I was thinking about things
like 'hello world', a calculator, an addressbook, a simple chat program.
Is the REST wiki a good place to start such a document, or should I
put it on the Ruby wiki? (the document could have different versions
for other programming languages as well).
Any suggestions would be most welcome.

   Erik Terpstra.

Don't know, and I think this list is for more general things, but I'd be
happy to participate wherever the work ends up happening.  A year ago I
would have said Yahoogroups.  ...suppose the thing to do is set up a mail
list anywhere convenient.

- Lucas

On Tue, 16 Apr 2002, bhaugen32 wrote:

> Lucas Gonze wrote:
> > I think there's a project to be done of working out a RESTy session
> > management protocol.  ...just have to sit down and do it, that's
> all.
>
> What would be the simplest or most generally congenial environment
> where a group could collaborate in some REST experiments?

Hi Erik,

There is already a page on the Wiki ("How to convert RPC to REST") for
what you are thinking about.  The fact that you didn't find it means that
there's a UI problem.  I have edited the text of the front page to
indicate that the "how to convert..." page includes examples.

Changed title
== Comparing REST to Other Things ==
to
== Comparing REST to Other Things: REST by Example ==

More examples on the HowToConvertRpcToRest page would be a good thing.

- Lucas

Lucas Gonze wrote:
> Don't know, and I think this list is for more general things, but
I'd be
> happy to participate wherever the work ends up happening.  A year
ago I
> would have said Yahoogroups.  ...suppose the thing to do is set up
a mail
> list anywhere convenient.

A Wiki works for me for conversation and documentation.  If the REST
Wiki admins don't want it, maybe set up another somewhere.

But I was also thinking about development environment, language,
server, etc. so components might work together more easily.  I know
REST doesn't care, but some of the head-scratching about REST that I
go through includes what happens behind the representation.

I don't care if it's something I don't know now (e.g. Ruby).
Should just be lightweight and simple and cheap (I think).

Erik wrote:
> However, I am not particularly interested in converting any existing
> technology into REST based ones.
>
> I am interested in simple (small) examples that demonstrate the REST
> approach with a 'readable' language like Ruby or Python, using only HTTP
> and URIS (and in more complex examples XML).

During the morning commute I came to more or less the same conclusion.
In general there needs to be a listing of design issues with an example
for each.  The stuff on the REST Wiki right now is too abstract.

Design issue: resources not methods
Example: SQL insert

One way to do a SQL insert over the web is to wrap the SQL in HTTP syntax.
For example,
GET /doInsert?cols=id,val&vals=25,fooVal&table=myTable

A REST way of doing this would
* be strict about not using GET to change server state
* have the back end target be a resource rather than a procedure

New way:
POST /tables/myTable?id=25&val=fooVal

- Lucas

Lucas Gonze wrote:
> There is already a page on the Wiki ("How to convert RPC to REST") for
> what you are thinking about.  The fact that you didn't find it means that

Thanks, but the top of that page states:
---
Here we aim to demonstrate by example how to convert existing XML-RPC or
SOAP/RPC based services into REST based ones that used only HTTP and
URIs (and optionally XML).
---

However, I am not particularly interested in converting any existing
technology into REST based ones.

I am interested in simple (small) examples that demonstrate the REST
approach with a 'readable' language like Ruby or Python, using only HTTP
and URIS (and in more complex examples XML).

    Erik.

http://api.google.com/search/beta2

Grrrr!

They used to have an XML interface via POST/GET. But you had to pay to get
in.
Don't know what happened to it.

----- Original Message -----
From: "Mark Baker" <distobj@...>
To: <rest-discuss@yahoogroups.com>
Sent: Wednesday, April 17, 2002 7:58 AM
Subject: [rest-discuss] Things that make you go "Grrrr!"


> http://api.google.com/search/beta2
>
> Grrrr!
>
>
> To unsubscribe from this group, send an email to:
> rest-discuss-unsubscribe@yahoogroups.com
>
>
>
> Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
>
>
>

----- Original Message -----
From: "Erik Terpstra" <erik@...>
>
> However, I am not particularly interested in converting any existing
> technology into REST based ones.
>
> I am interested in simple (small) examples that demonstrate the REST
> approach with a 'readable' language like Ruby or Python, using only HTTP
> and URIS (and in more complex examples XML).
>

What kind of code examples do you want - client or server?
How about Java code?

Regarding server based code, I have some Java code from a few years ago that
tried to be HTTP and resource oriented.
It's a still available at http://xml.apache.org/xang/ - there are two
pieces, a Servlet based framework for dispatching requests into 'resource
managers'. There is also a part that let you build the url structure and
method handlers in xml and script, but that might not be what you are
looking for (but xml and script do make for easy visual communication).

I also have some examples of a servlet using that approach to expose LDAP
and NNTP through simple URIs and as XML.
http://www.xmldatasource.com:7779/xds/ldap2xml/db.debian.org/ou=users/

There is also a project to do a 'canonical HTTP API for JMS' on sourceforge
(java & servlet based):
http://sourceforge.net/projects/destiny/

Something I haven't done but would like to is to write an HTTP client
library in Java that is an application API rather than a protocol API -
rather than talking about headers and stuff, talk about resources,
representations, etc.

Mark Baker wrote:
>
> http://api.google.com/search/beta2
>
> Grrrr!

I am half-way though an xml.com article on this topic. The argument in
favor of HTTP is so overwhelming that i would hope and expect that beta3
will have both interfaces. In fact, the SOAP interface feels like a
light layer of SOAP over a native HTTP interface already!

  Paul Prescod

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello Lucas,

On Thu, 18 Apr 2002 02:19, Lucas Gonze wrote:
> Erik wrote:
> > However, I am not particularly interested in converting any existing
> > technology into REST based ones.
> >
> > I am interested in simple (small) examples that demonstrate the REST
> > approach with a 'readable' language like Ruby or Python, using only HTTP
> > and URIS (and in more complex examples XML).

Erik: along side the address book example, what about a bookmark manager? It
could manage bookmarks in one central place.

> During the morning commute I came to more or less the same conclusion.
> In general there needs to be a listing of design issues with an example
> for each.  The stuff on the REST Wiki right now is too abstract.

As a very new comer to REST I am still having a hard time thinking about how
it works with a real application from an implementation point of view.

> Design issue: resources not methods
> Example: SQL insert
>
> One way to do a SQL insert over the web is to wrap the SQL in HTTP syntax.
> For example,
> GET /doInsert?cols=id,val&vals=25,fooVal&table=myTable
>
> A REST way of doing this would
> * be strict about not using GET to change server state
> * have the back end target be a resource rather than a procedure
>
> New way:
> POST /tables/myTable?id=25&val=fooVal
>
> - Lucas

Surely this would be very bad as anyone could insert whatever data they
wanted into your database. Database access/manipulation IMHO is something
that should definately live behind a facade. I would generally prefer to not
even expose dataaccess routines to the outside world but wrap those up in
something that communicates what the data is doing. Without doing a REST
example, because I don't understand it yet.

I would do something like employee.create, or update etc...This is commonly
termed as the CRUD approach. In REST would this be something like the
following?

http://somehost.com/employee/create?id=12345
http://somehost.com/employee/update?id=12345

Then on the server side there would be a create, update method on the
employee that takes an id parameter?

- --
Signed,
Holden Glova
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE8vnjn+mF116Lw2cQRAoddAJ9HIDZXui5D0I6yumnsY5kUVVE9QQCZAXdM
j3S51ro8ojOn+3kG4PMZqBE=
=uvr+
-----END PGP SIGNATURE-----

Please do not forward this too widely yet. I intend to publish it on
xml.com. In particular, please don't forward links to it yet. It's
canonical home should be xml.com. Still needs proof reading and comments
are welcome, as always.

=====

                         Google's Gaffe

Google's release of an Application Programming Interface has
been heralded as a bright moment for web services. It is true
that it is an exciting development, but at the same time there
is a subset of the programmer community that is disappointed.
Google had a similar XML-based API a year ago, but did not
document it or hype it. Merely by adding the URL fragment
"/xml" to your query, you could get back an XML representation
of a query, for processing by any XML-aware programming
language or tool. It became a pay-only service last fall. We
were disappointed but understood why that would happen -
lacking in advertisements, the service was a straight money
loser.

Imagine our surprise when we heard the big announcement
recently. Google had revived the service, added new features,
documented it and promoted it, but had moved it to a an
inferior technical platform: SOAP. Over dozens of mailing
lists, weblogs and discussion groups the reaction was mixed:
"An official Google API! But why use SOAP?" It feels like one
step forward and two backwards.

This article will demonstrate that the choice to use SOAP was
a poor one. The much simpler HTTP URI technique was easier to
use and more powerful at the same time. I will recast the new
Google API back into a URI and HTTP-based API and demonstrate
the virtues of the simpler HTTP strategy.

                      Why Google Is Special

In the past, I have demonstrated how SOAP-based services can
be re-engineered around pure HTTP. These services can be
arbitrarily complex, transactional, read-write and secure.
There are thousands of web services out there and I do not
have time to re-invent each and every one of them as
HTTP-based service. But the new Google API is special for a
variety of reasons.
  * Google has had an XML and HTTP based API in the past.
    Their choice to use SOAP would seem to indicate a need to
    move beyond HTTP. My experiment demonstrates that this is
    not so.
  * Google's service seems almost unique in how simply and
    clearly one can establish an HTTP interface. In essence,
    it feels like a thin SOAP wrapper over a simple HTTP
    service. Making an HTTP interface for Google is a
    "no-brainer".
  * Google the corporation has always been known for its
    technological acumen and general cluefulness. I think that
    they can be convinced to do the right thing and restore
    the HTTP interface (perhaps alongside the buzzword
    compliant SOAP interface).

In addition, I think that the Google move is important
symbolically. I take the SOAP-ifying of Google as a sign that
the web services hype has now reached overdrive. I now
regularly hear from customers that they have working XML
systems but: "we know we'll have to move to SOAP soon." This
is simply not true.

SOAP is an unproven technology with a questionable design.
Worse, when it is misused (as in the Google API) it has a
detrimental effect on the growth of the Web. As I will
demonstrate, at the heart of the Web is the concept of URIs.
The Google API substitutes a proprietary addressing mechanism
for URIs and thus hides information from Web-based software
such as XSLT engines and XInclude implementations.

                        Google's SOAP API

Let's take a look first at Google's SOAP API. This is our
starting point. Here is a complete message from client to
server using their API:

I set maxResults to 0 so that I won't actually get any
results. Google returns a ton of XML metadata about the query
itself so working with query "hits" would make my examples too
long.

The message starts with HTTP headers because the Google API
runs SOAP over HTTP. The only SOAP-specific header is the
SOAPAction header which is theoretically useful for filtering
SOAP traffic. Practically speaking it is optional and thus not
a good basis for filtering.

The XML part of the message starts with some namespace
declarations, and a SOAP encodingStyle declaration (more or
less boilerplate). After that comes a set of ordered
parameters. The parameters to the operation consist of an
ordered list of values. The allowed values for the
doGoogleSearch command is are "key" (userid/password), "q"
(query text), "start" (where in the results to start
returning), "maxResult" (number of allowed results), "filter"
(filtering out very similar results), "restrict" (country or
topic restrictions), "safeSearch" (pornography filter), "lr"
(language restrict), "ie" (input encoding) and "oe" (output
encoding) properties.

The "key" property is special. It is more or less a password
assigned to a particular software developer. The Google API
seems not to support SSL so these always pass across the wire
in cleartext.

As you can see, parameters are strongly typed. The client and
server know the types in advance but for some reason, most
SOAP toolkits will inline the types into the messages. As you
will see, this is entirely unnecessary.

Here is the message Google returns:

Note that the resultElements element is empty. I warned you
that we would have quite a bit of XML to work with even
without looking at any hits!

There are two more methods. doSpellingSuggestion requests a
spelling correction suggestion. For instance it would suggest
that "britney speers" be corrected to "britney spears". It
takes only a key and string as parameters, and returns only a
string for the suggestion.

doGetCachedPage requests a cached page from Google. It takes a
key and a URI as parameters and returns Base64-encoded data
for the cached page.

                         HTTP Equivalent

To reinvent this as an HTTP-based web service, I merely have
to translate the properties into "query parameters" in a URI.
A couple of hundred lines of Python serve to implement the
mapping from these query parameters into Google SOAP.

Here is the sort of URI used to address into my version of the
service:
http://localhost/scripts/search.py?key=0000&q=constantrevolution+rules+
xml&maxResults=10

That's pretty ugly, but consider that nobody (even a
programmer) ever needs to look at this URI. It can be
generated, just as the SOAP message is. For instance here is a
complete Python program to fetch the information from that
URI:
import urllib

params = {"key":"0000",
       "q":"constantrevolution rules xml",
       "maxResults":"0",
         }
urllib.urlopen("http://localhost/scripts/search.py?" +
     urllib.urlencode(params))

HTTP deals with optional arguments much more gracefully than
do most WSDL-based SOAP toolkits, so I've left out any of the
arguments that can be inferred or omitted.

Let's zoom in on the special key parameter. HTTP has a
built-in authentication mechanism so really that would be a
better way to handle it. Recent implementations of HTTP have a
challenge/response [1]authentication scheme which is more
secure than simply passing a key in cleartext. Of course for
ultimate security (at a price in performance), I would
recommend you SSL encrypt the entire message. SOAP does not
itself support authentication yet, and authentication is (as
of this writing) still an [2]open issuefor SOAP's
RPC-over-HTTP binding. I will leave key as a parameter for
simplicity and to more closely parallel the SOAP version.

Here is the message that gets sent on the wire:
GET /scripts/search.py?maxResults=0&key=XXX&q=constantrevolution+rules+
xml HTTP/1.0
Host: localhost
User-agent: Python-urllib

That's all!

Now some might complain that the query parameters are all
"just strings" whereas the SOAP parameters were strongly
typed. This is not necessarily true. On the wire, of course
the parameter are just strings, just as SOAP messages are just
strings. Only at the client and the server are the strings
interpreted as other types. The client must know the types of
the parameters in order to have made the call. The server must
know the types of the parameters in order to have implemented
the service. Given both parties already know the types, it is
a waste of bandwidth to declare the types of the parameters in
each and every message. Even SOAP does not require this. It is
merely a common SOAP idiom.

This leaves the question of how that is communicated. Later I
will show a way to declare the types strongly and statically
enough to satisfy the most ardent Java or C# masochist.

HTTP allows any media type in the response to a message. It
could return any XML vocabulary whatsoever. Insofar as the
Google SOAP API already embeds a simple schema, it makes sense
to use that. I merely have to remove a few SOAP-isms (the
arrayType attribute, the SOAP-env element, etc.) and choose a
new root element type (I chose searchResult). I hereby
christen the purified language GoogleML. I've written an XSLT
stylesheet that I call "pureGoogle.xsl" which translates
GoogleSOAP into GoogleML. The resulting documents are much
smaller, simpler and easier to read.

Here is the stylesheet (minus a few namespace declarations):

And here's a GoogleML equivalent to the response from before:

HTTP provides the envelope so there would be no need for a
redundant, second SOAP envelope. The types are known in
advance so they are stripped (although I could just as easily
have left them in). GoogleML documents are not constrained to
the features of XML supported by SOAP. GoogleML documents can
use a DOCTYPE and DTD, and could use processing instructions.

The most dramatic improvement comes in the getCachedPage
request. HTTP can efficiently handle non-XML data. HTTP
delivers terabytes of binary data every day. Conversely, SOAP
requires non-XML data to be Base-64 encoded (unless the use of
the non-standards-track SOAP With Attachments specification).
Base64 data is always more verbose than unencoded binary data
so the HTTP/URI/GoogleML version of the service will always
save bandwidth and CPU power.

Compare the SOAP doGetCachedPage request:

Now compare that to an HTTP-style cachedPage request:



Compare the SOAP response (embedding base64-encoded data):

to the HTTP-style response:

Because HTTP has no problem directly embedding HTML
(well-formed or not!), there is no reason to base64-encode the
data.

Finally compare the old-style SOAP doSpellingSuggestion
response:

To the HTTP version:

I could have used XML for the response, but why? It is
overkill for this job.

                         Declaring Types

Unfortunately many believe that the difference between
HTTP-based services and RPC-based services is that the former
are loosely or dynamically typed and the latter are strongly
or statically typed. This is not really true. The choice
between HTTP and SOAP is a choice between protocols. The
decision to statically type-check information passing across
the wire is more concerned with service description. The two
issues are totally separate.

I've already demonstrated how one can strongly type-declare
the responses to HTTP-based services using XML Schema. If you
want to type-declare the query parameters then you can use a
language designed for type-declaring HTTP-based services like
my Web Resource Description Language (WRDL).

WRDL is still under development but in fact you can already
solve this problem today using the more popular "industry
standard" language WSDL. WSDL has some basic HTTP-declaration
features. Although WSDL is most often used with SOAP, it can
in fact type-declare the parameters for simple HTTP services.
Here is the relevant bit of a WSDL for my HTTP version of the
doGetCachedPage method:

It turns out that WSDL's handling for the <http:urlEncoded/>
works almost perfectly. It gets the parameter names from the
operation's part names. If you know WSDL then that will
probably be clear to you. If not, don't worry about it. The
input description for the other two methods is identical, so
we will concentrate on the output element.

The output for the doSpellingSuggestion has a media-type of
"text/plain":

Finally, the output for doGoogleSearch

This refers to a part named searchResult which is based upon
an element type of the same name.

Now I do not want to oversell WSDL's HTTP features. You cannot
define sophisticated HTTP-based web services with WSDL. WSDL
falls down as soon as a web resource generates links to
another web resource. WSDL cannot express the data type of the
target resource. In other words it can describe only one
resource and not the links between Web resources. SOAP lacks a
first-class concept "of resource" and especially lacks a
syntax for linking them. It is thus not surprising that WSDL
inherits this flaw. Nevertheless, I hope that this weakness
will be corrected in future versions of WSDL. In the meantime,
this is the primary reason for the existence of the WRDL
language.

For instance, imagine if the search API returned a URI to the
cached page, just as it does in the HTML version of Google.
You could declared in WRDL (as opposed to WSDL) that the
cachedPage element of searchResult resources points to a
document of type text/html. I could also define a resource
type for Google "directory catalogs", then I have strong types
for the links from search results to the directory catalogs
and back. WRDL is designed (okay, being designed) to mirror
the structure of the Web, rather than impose a
component-oriented view on top of it.

Still and all, you do not have to wait for WRDL. WSDL is
sufficient for Google's current API because the API does not
make use of hyperlinks. This is a common failing of SOAP-based
APIs which follows from the component-centric thinking that
pervades the SOAP community.

                   Advantages of the HTTP API

Let's consider the benefits of the HTTP version. First, I have
already discussed how HTTP has standardized ways of doing
authentication and of handling non-XML (including non-textual)
data.

The message size is a tiny fraction of the original. More
important, it is much, much easier for a typical system
security administrator to read. It is also vastly easier to
filter, log and monitor. The CPU load is also likely to be
significantly smaller. I don't even want to know how many
cycles are being wasted around the world building those silly
Google SOAP messages (sometimes base64'ing data!) and then
parsing them down again on the other side. Remember that each
and every message is also an HTTP message and must be built
and parsed as such. Californian readers should remind Google
that electricity is precious. They could switch to HTTP and
turn off a couple of wasted server clusters.

I have no need to install a SOAP implementation like .NET's or
Apache's. You can use any HTTP implementation, including
Internet Explorer, Netscape, Mozilla, Lynx, Opera, wget,
"java.net.URL", Python's httplib.HTTPConnection, Perl's LWP,
etc. In fact, you could easily test the API through a plain
old HTML form!

The HTTP version is highly amenable to caching. You can set up
a standard HTTP cache on your local network, or use one at
your ISP. Google could also do server-side caching using
something as simple as Squid. Of course caching of SOAP is
also possible: if you write the cache implementation yourself.
With HTTP, you can install any one of a variety of free or
commercial caching proxy implementations.

The HTTP version could use the little-known feature of HTTP
known as content negotiation. "Conneg" as it is known to its
fans, allows each URI to map to a resource that can deliver up
various representations of itself. For instance the service
could return the same URI in GoogleML, SOAP, XML-RPC and HTML,
depending on the preferences of the caller.

But all of these advantages are like the tiny diamonds that
ring the Big Rock.

                    The Web's Crowning Glory

The most important advantage is that an HTTP version is part
of the Web rather than merely being behind the web. This point
is subtle but the most central. A piece of information is on
the Web if it has a URI or is embedded in a resource with a
URI. When I expose the Google API through SOAP it is behind
the Web because the object with the web URI is the SOAP
component, not the actual query results. Only the component is
on the Web. But in the HTTP way of thinking about it, every
possible query result has its own URI and thus is a
first-class web data object.

This assigning of URIs is incredibly powerful. First, it means
that in standard hypertext documents it is possible to link to
query results. There are thousands of links around the Web to
Google search result resources. Google's HTML incarnation is
an important part of the web community as a service but it is
also an important part of the web through the thousands of
virtual "resource documents" it hosts like:
[3]http://www.google.com/search?hl=en&q=xml+-soap

Now it is time to move this concept into XML. You may recall
the days when XML was intended to be a way of publishing
structured information on the Web. One of the great virtues
was [4]supposed tobe that result sets could be more compact
and could be manipulated (e.g. sorted and filtered) using
client-side scripting. Somehow I got sidetracked with RPC
models and SOAP, but the core idea of delivering XML to the
desktop is alive and well in [5]Internet Explorer and
[6]Mozilla.

Of course public websites cannot depend upon client-side XML
support being widely deployed yet, but companies like Google
should be laying the groundwork for a future XML-based Web
rather than burying XML for use only in machine to machine
applications. One of the virtues of XML we promoted in the
1997 edition of the XML Handbook was that XML brought the
representation of information for machines and humans
together. We still have not achieved that and will not until
machines and humans use the same access protocol: HTTP.

But URI-addressability is important even for information that
will never be seen by humans. Addressable XML can be composed
into extremely sophisticated "compound-documents" using
technologies like XInclude, XSLT, XLink, RDF and Topic Maps.
For instance, consider a document that uses XInclude to
aggregate query results:

Now consider an XSLT template that does the inclusions:

And then a template in another XSLT transform could collect
the URL and snippet elements in the merged data, sort them by
URL and transform them to HTML:

Next consider an RDF assertion that related the query results
to an individual's home pages:

This is the fundamental power of the Web. The Web's strength
is that it allows us to address, link, compare, relate and
otherwise combine resources. The point that has not yet
filtered through to the mainstream of web services
implementors is that this is just as important for machine to
machine applications as it is for human-facing applications.
To repeat: linking is just as important for machine to machine
applications as it is for human-facing applications. If it is
impossible to link to SOAP-exposed resources then they are
less powerful and useful than HTTP-exposed ones. Let me
rephrase that: until SOAP has an addressing mechanism as rich
as HTTP URIs, SOAP is less, not more, powerful than HTTP.

A less generous person might argue that SOAP services are
called "web services" because they wish to partake of the
Web's success -- yet do not wish to build upon its core
technologies: URIs and HTTP.

                         Service as API

An important issue in all of this is ease-of-use. If it is no
longer simple for programmers to access the information then
the service will fail.

Let's start from the point of view of a programmer with no
special toolkit at all, just a standard programming language
distribution or IDE. Obviously the HTTP solution wins because
SOAP and WSDL support is not yet embedded in most programming
language distributions. It takes five lines of Java to get a
cached page or spelling correct from my version of the
service. You don't need even an XML parser installed. Of
course working through search results will require an XML
parser but it will not require a SOAP engine on top.

On the other hand, what if you already have a SOAP/WSDL
toolkit? Well if the toolkit is complete (good luck!) then it
will support WSDL's HTTP binding. You can use exactly the same
API to access the service as if you were using the SOAP
version. For instance I can generate a statically typed C#
interface from my WSDL description and it is functionally
identical to the SOAP version. Truth in advertising: to get it
actually working I did have to work around a few small bugs in
Microsoft's WSDL toolkit. WSDL implementors: please take
WSDL's HTTP bindings seriously and implement them properly!
Note that there is also a prototype of a WRDL->C# tool which
will do the same for WRDL descriptions.

If you are opposed to external service descriptions, there are
a variety of inline-type annotation techniques you could use.
Examples include the OMG's XMI, Jacobson's MIME-RPC, Winer's
XML-RPC, Allaire's WDDL and even SOAP's "section 5" encoding.
No one of these has become standardized because the common
wisdom in the strongly typed XML world is that it will be much
more common to express the types in some form of external
schema such asXML Schema, RELAX NG, Schematron or DT4DTDs.
HTTP/WRDL works perfectly with all of these and unlike the
SOAP/WSDL combination has no preference for one over the
other.

If you like neither inline typing nor schemas then you have a
third choice: you can use a language-specific databinding
technology such as Castor, JAXB or [7].NET Data Binding.

In other words, parsing XML into language-native data types is
a problem that has been solved over and over again. If you
happen to prefer the SOAP solution then use the SOAP encoding.
SOAP is XML and can be used with various XML technologies. But
remember that you can use the SOAP encoding without buying the
whole SOAP RPC-over-HTTP model. If you use the SOAP encoding
with HTTP-based URIs then you preserve the essential heart of
the Web: the ability to address information.

                      What Would Frodo Do?

Back in the days where XML was called SGML, we enthusiasts
were like Hobbits in the Shire, hearing tales of the distant
wars between Wizards (tools vendors), Dragons (database
vendors) and Armies (MIS departments). But we were relatively
sheltered from them. Those days have long since passed. XML
users have a special understanding of the possibilities of the
marriage of hyperlinks, XML and the Web. We have a
responsibility to go out of the Shire and educate the other
residents of Middle Earth. Google is like the wizard Saruman,
a benign and powerful force inexplicably turned from the path
of virtue. Nevertheless, I am confident that they can be won
back! The white robe awaits on the delivery of the Google API
beta 3.

What we need to do is gather together a fellowship of
like-minded Hobbits, Dwarves, Elves and men and go on a quest
to improve the world in whatever small way we can. You can
join the quest by signing the [8]petition available , and if
you don't mind registering for Yahoo Groups, you can also
participate in the thread discussing this topic. Please
forward this article to mailing lists.

We must help our fellow technologists to use SOAP only after
they have understood its limitations and to understand that
they can make the Web a richer place by putting XML-based data
on the Web rather than behind it Yes, there are Wizards,
Dragons and Armies about, but Hobbits can influence events
also.

References

1. http://www.ietf.org/rfc/rfc2617.txt
2. http://www.w3.org/TR/soap12-part2/#simpleauthfeat
3. http://www.google.com/search?hl=en&q=xml+-soap

5. http://www.xml.com/pub/a/2000/05/03/msie/
6. http://www.mozilla.org/newlayout/xml/
7.
http://msdn.microsoft.com/msdnmag/issues/01/03/cutting/cutting0103.asp?frame=tru\
e

> Surely this would be very bad as anyone could insert whatever data they
> wanted into your database. Database access/manipulation IMHO is something
> that should definately live behind a facade. I would generally prefer to not
> even expose dataaccess routines to the outside world but wrap those up in
> something that communicates what the data is doing. Without doing a REST
> example, because I don't understand it yet.
>
> I would do something like employee.create, or update etc...This is commonly
> termed as the CRUD approach. In REST would this be something like the
> following?
>
> http://somehost.com/employee/create?id=12345
> http://somehost.com/employee/update?id=12345
>
> Then on the server side there would be a create, update method on the
> employee that takes an id parameter?

Hey Holden,

The REST answer to CRUD is that employee.create should not be exposed in a
broadly distributed setting because it is a method as opposed to a
resource.  So http://somehost.com/employee/create?id=12345 should be,
instead,

POST http://somehost.com/new_employees
(get back an ID, and then do...)

POST http://somehost.com/employees/$ID?department=accounting

So you wouldn't expose data access routines to the outside world, but you
would expose data access resources.  Then you just control access to the
data access resources using standard HTTP access control.  The net effect
is precisely to wrap up the SQL in something that controls access, a.k.a.
by exposing a public representatation of a private resource.

- Lucas

http://xmlhack.com/read.php?item=1615

"Amazon goes REST, Google goes SOAP"

  Paul Prescod

IBM just dropped a submarine patent on ebXML.
http://zdnet.com.com/2100-1106-884681.html

Follow this thread a little to see the consequent turmoil in ebXML-
related projects:
http://lists.ebtwg.org/archives/ebtwg/200204/msg00056.html

I work with ebXML and UN/CEFACT projects that model business
protocols independently of technical implementation.  I have been
looking very seriously at REST (as some of you know from previous
posts) and think that REST could handle all of the required business
protocols.

While I think the IBM will probably do something to remove the cloud
over ebXML, the fact remains that everything they said they
contributed and now claim patents over can be done in other ways,
that is, REST.

I am not a lawyer, but my guess is that using REST would have a
pretty good chance of avoiding the patent claims.  People who are
lawyers are examining the claims as we speak, and I'll post more
details as they become available (assuming there is interest).

-Bob Haugen

Patent number: 6,148,290
http://www.uspto.gov/patft/

or (the long URL):
http://patft.uspto.gov/netacgi/nph-Parser?
Sect1=PTO1&Sect2=HITOFF&d=PALL&p=1&u=/netahtml/srchnum.htm&r=1&f=G&l=5
0&s1='6,148,290'.WKU.&OS=PN/6,148,290&RS=PN/6,148,290

Seems to cover almost any kind of agreement on how to do business
electronically, including those conducted by humans at each end.

Lots of prior art has already come out of the woodwork.

I can't believe this.  Ok, I can.

Paul, it's wonderful!
Great argument, lots of convincing detail.

Suggestion for improvement:
If you could put something really short illustrating the difference
right after this paragraph, the attention-deficit reader (vast
majority) would not need to wade through so much before getting the
main point:

"This article will demonstrate that the choice to use SOAP was
a poor one. The much simpler HTTP URI technique was easier to
use and more powerful at the same time. I will recast the new
Google API back into a URI and HTTP-based API and demonstrate
the virtues of the simpler HTTP strategy."

<Put the main contrast here>
Google SOAP:
Google HTTP: