Use case comparison of REST & Web services

On Thu, Sep 19, 2002 at 10:06:43PM -0600, Champion, Mike wrote:
> OK, let's look at a use case.  Let's say I want to build a bot that
> tracks the scores of my favorite teams in real time and send me an IM
> when something "interesting" happens.  Let's also presume that various
> sites (CNN, the specific teams, maybe some local media) make this available
> in some machine-processable form over the Web.  How do we proceed?
> 
> In the SOAP/WSDL world, one finds the WSDL description of the service (from
> UDDI, Google, by world of mouth, or whatever), imports it into any one of
> a number of tools, and generates the code to do the actual getCurrentScore()
> or whatever invocation.

Let me do a side-by-side comparison of the steps taken in both
approaches.  My assumptions are;

- only XML, not RDF, for the REST style solution
- the same XML for each approach; XML that describes the score of a
sporting event.
- Web services are identified by URIs

1. Web services approach (no a priori knowledge of the interface to a
sport score);
- find the URI of the service via some means (billboard, Google, etc..)
- find the WSDL interface of the service via WS-Inspection
- generate code to retrieve data (stub)
- bind that to code that processes the data (client app)
- execute
- return score

2. REST approach;
- find the URI of the service via some means (billboard, Google, etc..)
- invoke GET which returns XML document
- feed that response to the code that processes the data
- return score

#1, due to the early-binding approach, intermixes design-time and
run-time artifacts; doing code-generation at run-time, for example.
#2 is all late-bound

An alternate Web services approach would be to have code that already
knew what the WSDL for a game score was.  If that's the case, then it
could do this;

3. Web services approach #2
- find the URI of the service via some means (billboard, Google, etc..)
- invoke the WSDL method which returns XML document
- feed that response to the code that processes the data
- return score

Both #2 and #3 are pretty darned similar, of course.  Each requires the
same bit of custom code to process the XML document.  The main
difference is that the code that retrieves the score over the network is
specific to scores for #3, and generic for everything with #2.  But
certainly both are equivalent in terms of their ability to do machine
processing on that data, since they can use the *same* code.

> Naturally it's posssible to do this RESTfully:
>   GET
> http://www.mediaconglomorate.com/scores/current/football/college?team=umichi
> gan
> [I live in Ann Arbor] or whatever to get some XML description the bot can
> use.  My question is  how does one find out the URL to GET,

The same way you find it for Web services.

> and how does one
> find out the format of the response?

The Content-Type header in the response.  I think we can all agree
that application/xml or application/soap+xml will be common values.

> (OK, in WSDL 1.2 it should be as easy as with SOAP today, but I don't think
> that's your point).
> 
> > A machine can work similarly.  Take the little-known anchor AII "rel",
> > which is used to declare the type of link between the current 
> > resource,
> > and the resource identified by the href value.  If Yahoo had written;
> > 
> > <a rel="http://terms.example.org/activities/athletic/sports/"
> >    href="http://www.yahoo.com/r/ys">Sports</a>
> > 
> > then a machine that recognized that URI as identifying the notion of
> > "sports" could follow the link, if that's what it was looking for.  Of
> > course, any app can follow any link, but it's a waste to get stuff you
> > don't need over a network; hence the value in declaring the type
> > alongside the link.
> 
> So how would this work in my example?  MediaConglomorate.com would have a
> human-readable page with <a rel="blah" href="blahblah"> elements describing
> the semantics of what I'd get by following the href links?

s/semantics/"resource type" - yes.

>  I can see how it
> would help a human writing the code, I can't see how a general tool could do
> it.

If you wrote some code that knew about teams, games, scores, etc.. all
the standardized types that the sports industry decides upon (and their
corresponding XML schemas), then you could write a program which
navigated through that information as required.

You might see;

<team>
  <nickname>Blue Jays</nickname>
  <city>Toronto</city>
  <sport>http://sports.example.org/types/sports/baseball/</sport>
  <league>http://www.mlb.com</league>
  <gameinfo>
    <current-game>http://bluejays.com/todays-game</current-game>
  </gameinfo>
</team>

So you just write code which parses that info, and knows that
"current-game" contains a URI which identifies the game resource.
Invoke GET on that and you get XML describing the current state of the
game; lineup, log, score, etc..  From there, you can get the player
info, stats, etc..

Automatable hypermedia navigation only needs a type system.

>  Sure, the world could define an XML standard for describing the HTTP
> GET/POST generation and the format of the result ... but I believe that's
> what WSDL is, no?

No, not primarily IMO.  WSDL's main goal, and most common use, is to
define application protocols.  It could be used to define HTTP's
uniform interface (though I think RFC 2616 does a better job).

> And someday Real Soon Now the "rel" link might point to a
> fragment of the Semantic Web that describes what to do, but I want to do
> this now.

Sure.  I'm not going to talk much about the Semantic Web, because people
just tune out when I do.  It adds a whole lot of value, and solves a big
scaling problem on the automatable Web (and for Web services), but I'll
leave that out, and try to compare apples-to-apples as best I can.

Also, by using URIs for types in this scenario, I'm not suggesting that
anything in particular be returned on a GET.  They're just identifiers.

> OK, explain in my scenario how this is done without a human reading a page
> and writing custom code?

Answered above, I believe.

>  Now explain how it would work for a non-idempotent
> operation, e.g., the software that the sportswriter uses to update the
> "scores" database?

Any software that knows what a "game score" document is, can update the
document then PUT it back to change it, if that's what it was instructed
to do.

>  I think we (mostly) all agree that WSDL should support
> raw HTTP GET/POST here as well as the SOAP RPC design pattern, but you seem
> to be saying that this could be done with just HTML descriptions.

I'm just using HTML to demonstrate the large amount of value in a
type system.  Going forward, I'd want XML there, of course.

> > Perhaps, but likely because they didn't consider how to use forms
> > in a machine processable environment.
> 
> Well, I suspect that "they" invented SOAP and WSDL because HTTP POST is so
> unconstrained that it required so much human communication to describe the
> format of the POST and the data sent back!  I don't doubt that a deeper
> understanding of Dr. Fielding's work would have led people in a somewhat
> different direction than the early versions of SOAP and WSDL took, and I
> agree that the RPC paradigm gets very, very messy when it comes face to face
> with the real unreliability/unpredictability/insecurity/anarchy of the
> Internet.  But you seem to be imply something much stronger, i.e. that
> nothing *like* SOAP and WSDL are really needed,

"imply"?!?! 8-)

> and I'm trying to figure out
> what it is.

Step 1;

- a type system where types are assigned URIs
- lots of XML schemas that use URIs to relate schema instances to other
instances (even of different schemas).

Step 2;
- RDF as a means of generalizing the assertions often hidden in
XML schemas and their processors

MB
-- 
Mark Baker, CTO, Idokorro Mobile (formerly Planetfred)
Ottawa, Ontario, CANADA.               distobj@acm.org
http://www.markbaker.ca        http://www.idokorro.com

Received on Friday, 20 September 2002 12:09:41 UTC