[uf-discuss] "Casual Web Services" and Well Designed Urls[uf-rest]

Sat Oct 21 00:42:07 PDT 2006

Mike Schinkel wrote to Microformats REST:

> After reading your email and those sections of Roy's paper I have 
> absolutely no idea what you were trying to communicate to me.

Let me begin by admitting that I don’t know what REST-based Web services
are. Given that you, Mike, were discussing REST-based Web services, I
may be off the mark. I’m discussing REST, with which I presume
REST-based Web services have at least something in common.

The structure of URLs is not important knowledge for any API for
applications of REST. In fact, the structure of URLs is totally
irrelevant to any such API.

> Roy's paper is written in such abstract language that I am unable
> to see the issues you bring up.  Maybe some examples would help?

The constraint of using hypermedia as the engine of application state 
can find alternate expression in the phrase, “Keep it linked, stupid” 
(KILS).

Consider an on-line directory of contact information. The publisher 
could specify bits of information and expect consumers to cobble the 
bits into URLs for further interaction:

<directory xmlns="data:,the%20Wrong%20Thing">
<contact><name>Jane Doe</name>
<department>Marketing</department>
<employeeID>97P1A</employeeID>
<photo hasPhoto="true"/></contact>
<!--...-->
</directory>

In this scenario, the publisher explains how consumers can and should 
construct the URLs <http://example.com/dept/marketing>, 
<http://example.com/dept/marketing/staff/97P1A>, and 
<http://example.com/dept/marketing/staff/97P1A/photo> given the 
directory document.

REST wants links in place of explanations:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head><title>Corporate directory</title></head>
<body><ul><li><a href=
"http://example.com/dept/marketing/staff/97P1A"
 >Jane Doe</a> (see <a href=
"http://example.com/dept/marketing/staff/97P1A/photo"
 >Jane’s photo</a>) works in <a href=
"http://example.com/dept/marketing"
 >marketing</a>.</li>
<!--...--></ul></body></html>

The links direct consumers, whether those consumers be humans with a Web 
browser or an automated program. When a program implements an API for an 
application of REST, the program relies on the presence of links in 
content. And when the program sifts content to discover links (rather 
than constructing URIs according to explanations), the structure of the 
URL which identifies the link’s target is irrelevant.

Why would the structure of the URLs matter to a program that works 
faithfully with an application of REST? What does the program lack or 
lose in the following example?

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head><title>Corporate directory</title></head>
<body><ul><li><a href=
"http://example.com/*z*?foo&"
 >Jane Doe</a> (see <a href=
"http://example.com/...narbley"
 >Jane’s photo</a>) works in <a href=
"http://example.com/%0D%25"
 >marketing</a>.</li>
<!--...--></ul></body></html>

-- 