Use Cases

[Paul Denning]

http://esw.w3.org/topic/WebDescriptionUseScenarios?highlight=%28CategoryWebDescription%29

Other use scenarios that come to mind:

1.  Comparing descriptions of two API's.  For example, scuttle may
claim to implement some/all of the del.icio.us API.
2.  Ability to mark a subset of an existing API; again, for example,
to show what subset of the del.icio.us API another similar service implements.

I find myself using a few social bookmarking systems: public
(del.icio.us), corporate intranet, work group (when the corporate
implementation chokes on some bookmarks).

I use bookmarklets and firefox extensions that work with one API
(i.e., del.icio.us), and I want to adapt them to work with the other
services.  This involves a comparison of what API subset a tool
(bookmarklet, browser extension) uses and what API subset an
alternative service implements.

Another interesting aspect of interface description is
redirection.  For example, [1] will redirect to [2].

[1] http://del.icio.us/url/?url=http%3A%2F%2Fesw.w3.org%2Ftopic%2FFrontPage
[2] http://del.icio.us/url/0d7a759146fad6ec8652c08cfcba98cc

Paul

[Mark Nottingham-4]

+1 - I've seen these situations come up.


On 2006/06/01, at 9:20 AM, Paul Denning wrote:

>
> http://esw.w3.org/topic/WebDescriptionUseScenarios?highlight=% 
> 28CategoryWebDescription%29
>
> Other use scenarios that come to mind:
>
> 1.  Comparing descriptions of two API's.  For example, scuttle may  
> claim to implement some/all of the del.icio.us API.
> 2.  Ability to mark a subset of an existing API; again, for  
> example, to show what subset of the del.icio.us API another similar  
> service implements.
>
> I find myself using a few social bookmarking systems: public  
> (del.icio.us), corporate intranet, work group (when the corporate  
> implementation chokes on some bookmarks).
>
> I use bookmarklets and firefox extensions that work with one API  
> (i.e., del.icio.us), and I want to adapt them to work with the  
> other services.  This involves a comparison of what API subset a  
> tool (bookmarklet, browser extension) uses and what API subset an  
> alternative service implements.
>
> Another interesting aspect of interface description is  
> redirection.  For example, [1] will redirect to [2].
>
> [1] http://del.icio.us/url/?url=http%3A%2F%2Fesw.w3.org%2Ftopic% 
> 2FFrontPage
> [2] http://del.icio.us/url/0d7a759146fad6ec8652c08cfcba98cc
>
> Paul
>
>
>

--
Mark Nottingham
mnot@...

[distobj]

On 6/1/06, Paul Denning <pauld@...> wrote:
>
> http://esw.w3.org/topic/WebDescriptionUseScenarios?highlight=%28CategoryWebDescription%29
>
> Other use scenarios that come to mind:
>
> 1.  Comparing descriptions of two API's.  For example, scuttle may
> claim to implement some/all of the del.icio.us API.
> 2.  Ability to mark a subset of an existing API; again, for example,
> to show what subset of the del.icio.us API another similar service implements.

Wouldn't you learn that via HTTP response codes?  e.g. 404 if a
resource wasn't there, 501 if a method wasn't supported, etc..?

> Another interesting aspect of interface description is
> redirection.  For example, [1] will redirect to [2].

Right, but again, that's information available in the HTTP response.
If you try to describe, in a separate document, that redirection
action then you've just duplicated information that is already
trivially accessible to clients.  Is there some advantage to doing
this that I'm not seeing?

Mark.

[Jan Algermissen]

Hi Mark,

except for HTTP and any shared MIME types, everything in a RESTful  
system is discovered at runetime. As it turns out (having just had  
that experience today, actually) developers demand more than HTTP and  
a MIME type at *design* time of any client side application. I am not  
sure from reading your response below if you consider runtime  
discoverable behaviour (e.g. response codes) or runtime discoverable  
forms to be used at design time. Do you?

IMHO, HTTP and the shared understanding of a MIME type *and* the  
intention of the client developer at design time are sufficient to  
actually implement the client side - if the design time expectations  
do not hold at runtime this will be detected at runtime. (I do not  
consider this a problem since there cannot be a design time  
constraint on the runtime in a distributed system anyhow so you  
allways need to check and expect insifficient data)

But the problem remains that whatever can be done, developers are  
likely to feel uncomfortable if they are not told at design time that  
"you have to post a purchase order to service X". So you end up  
giving them some sort of prescriptive schema (e.g. an XSD) and  
silently coupling the service implementation of POST to that  
expectation.

...admitedly, I got this feeling of security, too from the XSD...

Having said that, I think this is basically what the discussion about  
needing a description revolves around.

Jan



On Jun 7, 2006, at 3:34 PM, Mark Baker wrote:

>
> On 6/1/06, Paul Denning <pauld@...> wrote:
>>
>> http://esw.w3.org/topic/WebDescriptionUseScenarios?highlight=% 
>> 28CategoryWebDescription%29
>>
>> Other use scenarios that come to mind:
>>
>> 1.  Comparing descriptions of two API's.  For example, scuttle may
>> claim to implement some/all of the del.icio.us API.
>> 2.  Ability to mark a subset of an existing API; again, for example,
>> to show what subset of the del.icio.us API another similar service  
>> implements.
>
> Wouldn't you learn that via HTTP response codes?  e.g. 404 if a
> resource wasn't there, 501 if a method wasn't supported, etc..?
>
>> Another interesting aspect of interface description is
>> redirection.  For example, [1] will redirect to [2].
>
> Right, but again, that's information available in the HTTP response.
> If you try to describe, in a separate document, that redirection
> action then you've just duplicated information that is already
> trivially accessible to clients.  Is there some advantage to doing
> this that I'm not seeing?
>
> Mark.
>

[Tim Bray-3]

On Jun 7, 2006, at 10:59 AM, Jan Algermissen wrote:

> except for HTTP and any shared MIME types, everything in a RESTful  
> system is discovered at runetime.

Who said?  I disagree entirely.  Just because the SOAP-heads blew  
WSDL doesn't mean that there's anything intrinsically wrong with the  
notion of declaring a REST interface.  It would help with things like  
tooling and testing and automation, too.

> IMHO, HTTP and the shared understanding of a MIME type *and* the  
> intention of the client developer at design time are sufficient to  
> actually implement the client side - if the design time  
> expectations do not hold at runtime this will be detected at  
> runtime. (I do not consider this a problem since there cannot be a  
> design time constraint on the runtime in a distributed system  
> anyhow so you allways need to check and expect insifficient data)

My experience differs.  When building a heterogeneous distributed  
system, I'd like to have a contract that operates at a higher level  
than a MIME type, so that when things break, you can finger-point  
constructively.  -Tim

[noah_mendelsohn]

Tim Bray wrote:

> > except for HTTP and any shared MIME types, everything in a RESTful
> > system is discovered at runetime.
>
> Who said?  I disagree entirely.  Just because the SOAP-heads blew
> WSDL doesn't mean that there's anything intrinsically wrong with the
> notion of declaring a REST interface.  It would help with things like
> tooling and testing and automation, too.

I strongly agree.  (Well, it would be impolitic of me to agree with the
crack about the SOAP-heads blowing WSDL, so I'll just be neutral on that
and strongly agree on the rest, pun in tended.)  Anyway, long ago and far
away I gave a talk on XML Schema in which I claimed that schemas were
useful for at least 3 main purposes [1].

* Contracts:  agreeing on formats
* Tool building: know what the data will be
  before the first instance shows up
    - Database integration
    - User interface tools
    - Programming language bindings
* Validation:  make sure we got what
  we expected

As Tim says, you get just the same kinds of benefit by having a declared
description for a REST interface, and I'm not implying that the
description need in any way be based on XML Schema in particular.  The
description should be at whatever level and in whatever form meets the
above needs for you.

It's also true that it's a good thing if the runtime interaction is indeed
self-describing.  That's fundamental to the Web.  If you have no advance
description, then you need runtime self-description to understand what
you've got;  if you have an advance description, then the information
retrieved at runtime lets you "validate" that what you've received indeed
matches your expectations.  The runtime stuff always wins, but the advance
description can be very useful.

> > IMHO, HTTP and the shared understanding of a MIME type *and* the
> > intention of the client developer at design time are sufficient to
> > actually implement the client side - if the design time
> > expectations do not hold at runtime this will be detected at
> > runtime. (I do not consider this a problem since there cannot be a
> > design time constraint on the runtime in a distributed system
> > anyhow so you allways need to check and expect insifficient data)
>
> My experience differs.  When building a heterogeneous distributed
> system, I'd like to have a contract that operates at a higher level
> than a MIME type, so that when things break, you can finger-point
> constructively.  -Tim

Yup, I agree with that too.

Noah

[1] http://intertwingly.net/slides/2002/devcon/SchemaSecrets.ppt

--------------------------------------
Noah Mendelsohn
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------

[distobj]

On 6/7/06, Tim Bray <tbray@...> wrote:
> On Jun 7, 2006, at 10:59 AM, Jan Algermissen wrote:
>
> > except for HTTP and any shared MIME types, everything in a RESTful
> > system is discovered at runetime.
>
> Who said?  I disagree entirely.  Just because the SOAP-heads blew
> WSDL doesn't mean that there's anything intrinsically wrong with the
> notion of declaring a REST interface.

I agree.  REST says very little (in fact, nothing explicitly) about
design time vs. runtime.  Via the hypermedia constraint, it does quite
severely restrict how applications make forward progress, and that's
something we need to be aware of here.  But it certainly doesn't
preclude everything being discussed on this list.

HTTP already provides some "design time" information too.  OPTIONS
responses, for example.  The Allow response header.  Probably other
things.

>  It would help with things like
> tooling and testing and automation, too.

I think that's part of what we're trying to determine.  Having built a
handful of machine-to-machine Web based systems, none of which needed
a "description language" (nor would they have benefitted from one,
IMO), I'm skeptical that there's a big enough problem here that
requires a new standard (rather than reusing, say, XForms).  But I'm
happy to be convinced otherwise.

> > IMHO, HTTP and the shared understanding of a MIME type *and* the
> > intention of the client developer at design time are sufficient to
> > actually implement the client side - if the design time
> > expectations do not hold at runtime this will be detected at
> > runtime. (I do not consider this a problem since there cannot be a
> > design time constraint on the runtime in a distributed system
> > anyhow so you allways need to check and expect insifficient data)
>
> My experience differs.  When building a heterogeneous distributed
> system, I'd like to have a contract that operates at a higher level
> than a MIME type, so that when things break, you can finger-point
> constructively.  -Tim

Sorry, I don't understand what you mean by that.

Mark.

[Mark Nottingham-4]

I'm finding that my biggest use case for a Web description format (at  
the risk of repeating myself) is at design time; architects and  
developers need something that encourages them to think in terms of  
stateful resources, and a common documentation format is immensely  
helpful.

There are other cases -- e.g., generating stubs, hinting  
configuration, etc., but I think that's the big one.


On 2006/06/08, at 7:18 PM, Mark Baker wrote:

> I think that's part of what we're trying to determine.  Having built a
> handful of machine-to-machine Web based systems, none of which needed
> a "description language" (nor would they have benefitted from one,
> IMO), I'm skeptical that there's a big enough problem here that
> requires a new standard (rather than reusing, say, XForms).  But I'm
> happy to be convinced otherwise.

--
Mark Nottingham
mnot@...

[Jan Algermissen]

On Jun 9, 2006, at 4:18 AM, Mark Baker wrote:

>
> HTTP already provides some "design time" information too.  OPTIONS
> responses, for example.  The Allow response header.  Probably other
> things.

Maybe some agreement on terms is necessary here. I understand design  
time information to serve as a contract between client and server  
that is guaranteed to be stable at runtime. IOW, a contract that can  
go into the design, usually by more or less hardcoding it.

Having said that, could you clarify wheather why you consider OPTIONS  
and Allow to provide design time information in *that* sense.

To put this in other words: Since the server can change at any time  
the response it sends for a given OPTIONS request, of what use is  
such a response rearding any conract between client and server?

Jan

>
>>  It would help with things like
>> tooling and testing and automation, too.
>
> I think that's part of what we're trying to determine.  Having built a
> handful of machine-to-machine Web based systems, none of which needed
> a "description language" (nor would they have benefitted from one,
> IMO), I'm skeptical that there's a big enough problem here that
> requires a new standard (rather than reusing, say, XForms).  But I'm
> happy to be convinced otherwise.
>
>> > IMHO, HTTP and the shared understanding of a MIME type *and* the
>> > intention of the client developer at design time are sufficient to
>> > actually implement the client side - if the design time
>> > expectations do not hold at runtime this will be detected at
>> > runtime. (I do not consider this a problem since there cannot be a
>> > design time constraint on the runtime in a distributed system
>> > anyhow so you allways need to check and expect insifficient data)
>>
>> My experience differs.  When building a heterogeneous distributed
>> system, I'd like to have a contract that operates at a higher level
>> than a MIME type, so that when things break, you can finger-point
>> constructively.  -Tim
>
> Sorry, I don't understand what you mean by that.
>
> Mark.
>

[Jan Algermissen]

On Jun 9, 2006, at 4:18 AM, Mark Baker wrote:
>
> On 6/7/06, Tim Bray <tbray@...> wrote:
>> [...] When building a heterogeneous distributed
>> system, I'd like to have a contract that operates at a higher level
>> than a MIME type, so that when things break, you can finger-point
>> constructively.  -Tim
>
> Sorry, I don't understand what you mean by that.
>

Assuming a business context and the use of XSD, I think Tim is saying  
that a MIME type would usually define some set of business object  
types (e.g. person, invoice) including relationship semantics. I  
think he'd expect a resource that accepts data submission via POST to  
explicitly state what the type of the objects is, that it accepts as  
input (e.g. "I'll take XML input that conforms to the person content  
model of the XSD"). This infomation can be used by developers at  
design time to know that they are expected to consruct a person  
object and send it off.

If the resource just says that it accepts the MIME type then you do  
not get that information (that contract), all the client developer  
can know is that it must send that MIME type - but what kind of  
message??

If the resource some time receives an invoice instance, you'd know  
that the contract of "needing a person" has been violated. The same  
applies to the server on day switching to accept invoices, but not  
persons anymore.

Does that clarify?

Jan



> Mark.
>

[Jan Algermissen]

Hi Mark,

just came across this[1] earlier related exchange; a good chance to  
restate my question in other words.

You wrote:

"Well, there's got to be other information provided with the form that
your app can use to decide if it's going to take any of the actions
described by the form."

When you say "information [...] that your app can use to decide", do  
you refer to the time the app is built (or configured) or to the time  
the app actually consumes the form in its runtime interactions with  
the service.

IMHO it should be the latter - I think the former leads to  
uneccessary coupling.

Jan

On Jun 10, 2006, at 5:18 PM, Jan Algermissen wrote:

>
>
> On Jun 9, 2006, at 4:18 AM, Mark Baker wrote:
>
>>
>> HTTP already provides some "design time" information too.  OPTIONS
>> responses, for example.  The Allow response header.  Probably other
>> things.
>
> Maybe some agreement on terms is necessary here. I understand  
> design time information to serve as a contract between client and  
> server that is guaranteed to be stable at runtime. IOW, a contract  
> that can go into the design, usually by more or less hardcoding it.
>
> Having said that, could you clarify wheather why you consider  
> OPTIONS and Allow to provide design time information in *that* sense.
>
> To put this in other words: Since the server can change at any time  
> the response it sends for a given OPTIONS request, of what use is  
> such a response rearding any conract between client and server?
>
> Jan
>
>>
>>>  It would help with things like
>>> tooling and testing and automation, too.
>>
>> I think that's part of what we're trying to determine.  Having  
>> built a
>> handful of machine-to-machine Web based systems, none of which needed
>> a "description language" (nor would they have benefitted from one,
>> IMO), I'm skeptical that there's a big enough problem here that
>> requires a new standard (rather than reusing, say, XForms).  But I'm
>> happy to be convinced otherwise.
>>
>>> > IMHO, HTTP and the shared understanding of a MIME type *and* the
>>> > intention of the client developer at design time are sufficient to
>>> > actually implement the client side - if the design time
>>> > expectations do not hold at runtime this will be detected at
>>> > runtime. (I do not consider this a problem since there cannot be a
>>> > design time constraint on the runtime in a distributed system
>>> > anyhow so you allways need to check and expect insifficient data)
>>>
>>> My experience differs.  When building a heterogeneous distributed
>>> system, I'd like to have a contract that operates at a higher level
>>> than a MIME type, so that when things break, you can finger-point
>>> constructively.  -Tim
>>
>> Sorry, I don't understand what you mean by that.
>>
>> Mark.
>>
>
>

[Jan Algermissen]

[Sorry, hit "send" too fast, here is the reference:]
http://lists.w3.org/Archives/Public/public-web-http-desc/2005Jun/ 
0031.html
Jan

I wrote:

Hi Mark,

just came across this[1] earlier related exchange; ...

[distobj]

On 6/10/06, Jan Algermissen <jalgermissen@...> wrote:
> To put this in other words: Since the server can change at any time
> the response it sends for a given OPTIONS request, of what use is
> such a response rearding any conract between client and server?

It's a matter of degree, I suppose.  You don't expect methods on a
resource to change frequently, so depending on it at design time is
probably not such a big deal.

If you can write software that doesn't depend on that information,
that's always best (I hope everybody agrees on that, at least!), and
it's what I've personally done and will always try to do.  But I can't
rule out the possibility that the benefits of knowing that kind of
information at design time won't help in some cases; I doubt it, but I
suppose it's possible.

Mark.

[Paul Downey]

On 11 Jun 2006, at 11:01, Jan Algermissen wrote:

> When you say "information [...] that your app can use to decide",  
> do you refer to the time the app is built (or configured) or to the  
> time the app actually consumes the form in its runtime interactions  
> with the service.

How can you tell if someone takes a HTML page and uses it to display  
a form,
or uses it to generate Java code, builds it, and then some time later  
sends
the same HTTP request?

> IMHO it should be the latter - I think the former leads to  
> uneccessary coupling.

IMHO making such a distinction is unnecessary coupling.

Paul
--
http://blog.whatfettle.com

[Jan Algermissen]

On Jun 12, 2006, at 11:09 PM, Paul Downey wrote:

>
> On 11 Jun 2006, at 11:01, Jan Algermissen wrote:
>
>> When you say "information [...] that your app can use to decide",  
>> do you refer to the time the app is built (or configured) or to  
>> the time the app actually consumes the form in its runtime  
>> interactions with the service.
>
> How can you tell if someone takes a HTML page and uses it to  
> display a form,
> or uses it to generate Java code, builds it, and then some time  
> later sends
> the same HTTP request?

Well, the issue here is what happens when the service implementation  
changes. REST's programming model motivates the idea that (within  
reasonable boundaries of course) the service should be able to evolve  
(change it's interface) without breaking any existing client; as long  
as the service sticks to the MIME type that defines the shared  
semantics between clients and server.

>
>> IMHO it should be the latter - I think the former leads to  
>> uneccessary coupling.
>
> IMHO making such a distinction is unnecessary coupling.
>

Hmm...why?

Jan

> Paul
> --
> http://blog.whatfettle.com
>