Loading ...
Sorry, an error occurred while loading the content.
 

Service descriptions and legal contracts

Expand Messages
  • Jan Algermissen
    Hi- Occasionally demand is heard for service descriptions for services in RESTful systems. Clearly, such descriptions are contrary to REST s evolvability goals
    Message 1 of 25 , Nov 5, 2009
      Hi-

      Occasionally demand is heard for service descriptions for services in
      RESTful systems. Clearly, such descriptions are contrary to REST's
      evolvability goals because any prescriptive information about the
      server limits its desired evolvability.

      While this is fine when the client has human or human-like
      capabilities to mediate between the overall client's intentions (e.g.
      'buying a book') and the actual runtime-discovered state machine of
      the application, problems do arise when the communication model is
      applied to machine to machine interactions. Especially when REST is
      applied in an enterprise context where budgets and legal issues are at
      stake.

      The problem is that an overall goal like 'buying a book' must assume
      the availability of certain media types, extensions, links, etc. and
      certain available state transitions at certain points in the overall
      interaction. Without such assumptions it would be impossible to come
      up with client side code that performs the overall goal.

      With human clients the situation is actually quite the same but less
      visible because the human user is sort of in permanent browsing mode,
      walking the Web, discovering new things, etc. When underlying
      expectations fail (Ooops, where did that 1-Click link go?)
      compensating action can be taken. For example: call the hotline or
      change the online shop.

      One can put some amount of flexibility into a machine client, but it
      is inevitable that at some point assumptions end up in a place (source
      code, configuration) that will cause runtime failure when the
      assumptions about the server turn out to be wrong.

      This is not so much of a problem in contexts, where budget and legal
      issues are of minor importance (e.g. when I do some fun-coding to
      interact with Amazon's APIs) but as soon as you pay serious amounts
      for the use of an API or when liability issues are involved things are
      different.

      What is necessary I think is a way to describe services that meets the
      following objectives:

      1. **Only** describe/define those aspects of the provided
      service that constitute an inevitable coupling of
      client and server anyway. For example: if a client
      is programmed to use a search, the service provider
      must assure that the search will remain available
      during the agreed upon service lifetime.

      2. Use a means of description that is formal enough to
      serve as the basis for legal contracts (e.g. SLAs).

      3. Make that means of description standard/mainstream
      enough to avoid that everybody is forced to reinvent
      the wheel[1]


      These are the aspects I think should be addressed in such definitions:

      1. General client obligations
      This section would cover the base set of media types,
      link relations, etc. to be understood by the client.

      2. General server commitments
      The description can be simplified and reduced if the
      server makes general commitments such as 'resources
      that are known by the client to be collections of items
      will always at least be available as application/atom+xml

      3. General availability of certain state transitions
      A search resource for example can be defined to be available
      to the client independent of the current application state.
      IOW, the search resource will always be 'announced' as
      part of the initial service documents or, if none are used
      it would mean that the search would be available to the
      client from any received response (e.g. via Link header)

      4. Availability of certain goals in certain application states
      If a client does a search in an online shop there is an
      expectation to being able to place an order afterwards.
      Such an expectation would be backed up by this section. A
      way to view this is as a dependency tree of goals (after
      item search can come purchase).

      5. Availability of certain media types, link relations,
      extensions There must be a means for the server to tell the
      client which media types are available[2] and also a
      commitment that these (or at least one) will remain in use
      for a defined period of time.

      [1] This is AFAIU the major concern articulated by Steve Jones in 2nd
      paragraph of <http://tech.groups.yahoo.com/group/service-orientated-architecture/message/13909
      >
      (a discussion that is the origin of this post because he makes some
      valid points
      there)

      [2] Sure, the client could determine this at design time by executing
      the service, but on the one hand, this does not provide the designer
      with a guaranteed exhaustive set of options (you never know what you
      did not see) and on the other hand this approach is not likely to be
      helpful when proposing a project to whoever assigns you the budget.

      Jan
















      --------------------------------------
      Jan Algermissen

      Mail: algermissen@...
      Blog: http://algermissen.blogspot.com/
      Home: http://www.jalgermissen.com
      --------------------------------------
    • Subbu Allamaraju
      ... Prose meets all these objectives. Plus it is also interoperable between all parties involved. Subbu
      Message 2 of 25 , Nov 5, 2009
        > What is necessary I think is a way to describe services that meets the
        > following objectives:
        >
        > 1. **Only** describe/define those aspects of the provided
        > service that constitute an inevitable coupling of
        > client and server anyway. For example: if a client
        > is programmed to use a search, the service provider
        > must assure that the search will remain available
        > during the agreed upon service lifetime.
        >
        > 2. Use a means of description that is formal enough to
        > serve as the basis for legal contracts (e.g. SLAs).
        >
        > 3. Make that means of description standard/mainstream
        > enough to avoid that everybody is forced to reinvent
        > the wheel[1]
        >

        Prose meets all these objectives. Plus it is also interoperable
        between all parties involved.

        Subbu
      • wahbedahbe
        ... There are a lot of assumptions here about the limitations of machine to machine RESTful interaction. I have never seen any proof of these limitations. It
        Message 3 of 25 , Nov 5, 2009
          --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
          >
          > Hi-
          >
          > Occasionally demand is heard for service descriptions for services in
          > RESTful systems. Clearly, such descriptions are contrary to REST's
          > evolvability goals because any prescriptive information about the
          > server limits its desired evolvability.
          >
          > While this is fine when the client has human or human-like
          > capabilities to mediate between the overall client's intentions (e.g.
          > 'buying a book') and the actual runtime-discovered state machine of
          > the application, problems do arise when the communication model is
          > applied to machine to machine interactions. Especially when REST is
          > applied in an enterprise context where budgets and legal issues are at
          > stake.
          >
          > The problem is that an overall goal like 'buying a book' must assume
          > the availability of certain media types, extensions, links, etc. and
          > certain available state transitions at certain points in the overall
          > interaction. Without such assumptions it would be impossible to come
          > up with client side code that performs the overall goal.
          >
          > With human clients the situation is actually quite the same but less
          > visible because the human user is sort of in permanent browsing mode,
          > walking the Web, discovering new things, etc. When underlying
          > expectations fail (Ooops, where did that 1-Click link go?)
          > compensating action can be taken. For example: call the hotline or
          > change the online shop.
          >
          > One can put some amount of flexibility into a machine client, but it
          > is inevitable that at some point assumptions end up in a place (source
          > code, configuration) that will cause runtime failure when the
          > assumptions about the server turn out to be wrong.
          >
          > This is not so much of a problem in contexts, where budget and legal
          > issues are of minor importance (e.g. when I do some fun-coding to
          > interact with Amazon's APIs) but as soon as you pay serious amounts
          > for the use of an API or when liability issues are involved things are
          > different.
          >

          There are a lot of assumptions here about the limitations of machine to machine RESTful interaction. I have never seen any proof of these limitations. It just seems that because the general REST community can't figure out how to design good media types for machine to machine interaction, the consensus is that it isn't possible.

          The thing is that I work in an industry where a media type for machine to machine, RESTful interaction has been available for years. Many client implementations are commercially available and all sorts of applications have been written by 3rd parties *after* the media type was designed, and the clients were built and sold. The clients are completely decoupled from the services because the services didn't exist when the clients were written. That is the way the web is; that is how REST is supposed to work.

          The media type I'm talking about is CCXML: http://www.w3.org/TR/ccxml/
          The industry I'm talking about is telecom -- where 5 9s are expected otherwise you get sued for millions. So I have a hard time buying into these sorts of arguments when it seems that I've been working with a counter example for years.

          I've been encouraging folks on this list to look at CCXML for a long time, but as far as I know I haven't convinced anyone to spend the time. Hey -- maybe CCXML isn't RESTful after all; it certainly has a different flavor than most of the media types coming from the REST community. I'd love to get all of your feedback; maybe I'm missing something. But if it isn't then perhaps the as yet to be formally defined style behind CCXML is a good alternative to REST for machine to machine interaction. It certainly seems to have many of the properties most readers of this list are looking for.

          Anyways, I encourage you to take a look at CCXML. I think it will be worth your time, and I think that the discussions that might ensue will be very valuable.
          Regards,

          Andrew
        • Jan Algermissen
          ... I did not say that at all. Of course machine to machine RESTful systems are possible (e.g. AtomPub). I was talking about inevitable assumptions the client
          Message 4 of 25 , Nov 5, 2009
            On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:

            > There are a lot of assumptions here about the limitations of machine
            > to machine RESTful interaction. I have never seen any proof of these
            > limitations. It just seems that because the general REST community
            > can't figure out how to design good media types for machine to
            > machine interaction, the consensus is that it isn't possible.

            I did not say that at all. Of course machine to machine RESTful
            systems are possible (e.g. AtomPub). I was talking about inevitable
            assumptions the client has to make that manifest itself in code or
            configuration of and how to document these such that

            - no unnecessary coupling is created by the documentation
            (as is by many of the documentations of the so called REST
            interfaces on the Web)
            - the style of documentation will be accepted by e.g.
            the legal department

            Jan
          • Jan Algermissen
            ... Sure prose is appropriate (never suggested otherwise). But just saying use prose does not address 3. above. This was one of the points made by Steve
            Message 5 of 25 , Nov 5, 2009
              On Nov 5, 2009, at 4:31 PM, Subbu Allamaraju wrote:

              >> What is necessary I think is a way to describe services that meets
              >> the
              >> following objectives:
              >>
              >> 1. **Only** describe/define those aspects of the provided
              >> service that constitute an inevitable coupling of
              >> client and server anyway. For example: if a client
              >> is programmed to use a search, the service provider
              >> must assure that the search will remain available
              >> during the agreed upon service lifetime.
              >>
              >> 2. Use a means of description that is formal enough to
              >> serve as the basis for legal contracts (e.g. SLAs).
              >>
              >> 3. Make that means of description standard/mainstream
              >> enough to avoid that everybody is forced to reinvent
              >> the wheel[1]
              >>
              >
              > Prose meets all these objectives. Plus it is also interoperable
              > between all parties involved.

              Sure prose is appropriate (never suggested otherwise). But just saying
              'use prose' does not address 3. above. This was one of the points made
              by Steve Jones: given that WS-* has a rigid interface description
              language 'built in' while the use of REST means you have to come up
              with a means of describing interfaces yourself is a huge selling point
              for WS-*. Not that having such things as WSDL and BPEL is desireable
              from a networked systems point of view but when a non technical person
              has to make a business decision about WS-* vs REST, the latter is more
              likely to 'loose' if you first have to come up with a style for
              documenting the interfaces. And even worse would be the position of
              'Nah, you don't need that. Just let everyone write it up'.

              Jan





              >
              > Subbu
              >
              >
              > ------------------------------------
              >
              > Yahoo! Groups Links
              >
              >
              >

              --------------------------------------
              Jan Algermissen

              Mail: algermissen@...
              Blog: http://algermissen.blogspot.com/
              Home: http://www.jalgermissen.com
              --------------------------------------
            • Jan Algermissen
              ... From the TR: A CCXML session begins with the execution of a CCXML document. Now, my understanding might be wrong because I dod not have the time to put
              Message 6 of 25 , Nov 6, 2009
                On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:

                > I've been encouraging folks on this list to look at CCXML for a long
                > time, but as far as I know I haven't convinced anyone to spend the
                > time. Hey -- maybe CCXML isn't RESTful after all; it certainly has a
                > different flavor than most of the media types coming from the REST
                > community. I'd love to get all of your feedback; maybe I'm missing
                > something. But if it isn't then perhaps the as yet to be formally
                > defined style behind CCXML is a good alternative to REST for machine
                > to machine interaction. It certainly seems to have many of the
                > properties most readers of this list are looking for.


                From the TR: "A CCXML session begins with the execution of a CCXML
                document."

                Now, my understanding might be wrong because I dod not have the time
                to put my head into the spec, but the above quote sounds a lot like
                that the coordination between components in CCXML is achieved by
                passing code (executable documents) around. To be RESTful the
                coordination should be achieved by passing representations of state
                around.

                Can you provide us with an example of a typical interaction?

                Jan




                --------------------------------------
                Jan Algermissen

                Mail: algermissen@...
                Blog: http://algermissen.blogspot.com/
                Home: http://www.jalgermissen.com
                --------------------------------------
              • Bob Haugen
                ... Passing executable code is one of the features of REST: 5.1.7 Code-On-Demand That doesn t prove CCXML to be RESTful, but doesn t rule it out, either.
                Message 7 of 25 , Nov 6, 2009
                  On Fri, Nov 6, 2009 at 2:42 AM, Jan Algermissen <algermissen1971@...> wrote:
                  > From the TR: "A CCXML session begins with the execution of a CCXML
                  > document."
                  >
                  > Now, my understanding might be wrong because I dod not have the time
                  > to put my head into the spec, but the above quote sounds a lot like
                  > that the coordination between components in CCXML is achieved by
                  > passing code (executable documents) around. To be RESTful the
                  > coordination should be achieved by passing representations of state
                  > around.

                  Passing executable code is one of the features of REST:
                  5.1.7 Code-On-Demand

                  That doesn't prove CCXML to be RESTful, but doesn't rule it out, either.
                • Jan Algermissen
                  ... Yes, thought about that, too. ... Right. But it seems like the primary corrdination means of CCXML and I guess that would make it non REST . (given my
                  Message 8 of 25 , Nov 6, 2009
                    On Nov 6, 2009, at 1:12 PM, Bob Haugen wrote:

                    > On Fri, Nov 6, 2009 at 2:42 AM, Jan Algermissen <algermissen1971@...
                    > > wrote:
                    >> From the TR: "A CCXML session begins with the execution of a CCXML
                    >> document."
                    >>
                    >> Now, my understanding might be wrong because I dod not have the time
                    >> to put my head into the spec, but the above quote sounds a lot like
                    >> that the coordination between components in CCXML is achieved by
                    >> passing code (executable documents) around. To be RESTful the
                    >> coordination should be achieved by passing representations of state
                    >> around.
                    >
                    > Passing executable code is one of the features of REST:
                    > 5.1.7 Code-On-Demand

                    Yes, thought about that, too.

                    >
                    > That doesn't prove CCXML to be RESTful, but doesn't rule it out,
                    > either.

                    Right. But it seems like the primary corrdination means of CCXML and
                    I guess that would make it 'non REST'. (given my glimples at the spec
                    is enough).

                    Jan


                    >
                    >
                    > ------------------------------------
                    >
                    > Yahoo! Groups Links
                    >
                    >
                    >

                    --------------------------------------
                    Jan Algermissen

                    Mail: algermissen@...
                    Blog: http://algermissen.blogspot.com/
                    Home: http://www.jalgermissen.com
                    --------------------------------------
                  • wahbedahbe
                    ... Right, but it s the assumption that these out-of-band contracts are needed is what I m questioning. They don t seem to be needed in the human web. Sure you
                    Message 9 of 25 , Nov 6, 2009
                      --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
                      >
                      >
                      > On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:
                      >
                      > > There are a lot of assumptions here about the limitations of machine
                      > > to machine RESTful interaction. I have never seen any proof of these
                      > > limitations. It just seems that because the general REST community
                      > > can't figure out how to design good media types for machine to
                      > > machine interaction, the consensus is that it isn't possible.
                      >
                      > I did not say that at all. Of course machine to machine RESTful
                      > systems are possible (e.g. AtomPub). I was talking about inevitable
                      > assumptions the client has to make that manifest itself in code or
                      > configuration of and how to document these such that
                      >
                      > - no unnecessary coupling is created by the documentation
                      > (as is by many of the documentations of the so called REST
                      > interfaces on the Web)
                      > - the style of documentation will be accepted by e.g.
                      > the legal department
                      >
                      > Jan
                      >

                      Right, but it's the assumption that these out-of-band contracts are needed is what I'm questioning. They don't seem to be needed in the human web. Sure you may need to document the representation formats -- the media type and the extensions and rels necessary to use the service. But its things like guarantees about what "kinds of state transitions" are available that I question. I'm not sure that the "inevitable assumptions" you refer to are necessary. Maybe I'm reading too much into what you mean by that though, but it seems to be more that what normally constitutes the uniform interface. Maybe I need more clarification on what you think would be in this contract.
                      Regards,

                      Andrew
                    • Jan Algermissen
                      ... Suppose you are coding a client for service that lets you search stuff and then do something with it (e.g. update). Your client code will inevitably
                      Message 10 of 25 , Nov 6, 2009
                        On Nov 6, 2009, at 3:36 PM, wahbedahbe wrote:

                        > --- In rest-discuss@yahoogroups.com, Jan Algermissen
                        > <algermissen1971@...> wrote:
                        >>
                        >>
                        >> On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:
                        >>
                        >>> There are a lot of assumptions here about the limitations of machine
                        >>> to machine RESTful interaction. I have never seen any proof of these
                        >>> limitations. It just seems that because the general REST community
                        >>> can't figure out how to design good media types for machine to
                        >>> machine interaction, the consensus is that it isn't possible.
                        >>
                        >> I did not say that at all. Of course machine to machine RESTful
                        >> systems are possible (e.g. AtomPub). I was talking about inevitable
                        >> assumptions the client has to make that manifest itself in code or
                        >> configuration of and how to document these such that
                        >>
                        >> - no unnecessary coupling is created by the documentation
                        >> (as is by many of the documentations of the so called REST
                        >> interfaces on the Web)
                        >> - the style of documentation will be accepted by e.g.
                        >> the legal department
                        >>
                        >> Jan
                        >>
                        >
                        > Right, but it's the assumption that these out-of-band contracts are
                        > needed is what I'm questioning.

                        Suppose you are coding a client for service that lets you search stuff
                        and then do something with it (e.g. update). Your client code will
                        inevitably contain the 'invocation' of the search (e.g. GET request to
                        search resource). And this is based on the expectation that the search
                        resource will be there (== being discoverable). If the service does
                        not provide the search resource anymore the client will break (if you
                        code it to expect that there is a search resource and sudden;y there
                        is none what else could the code do?). Humans can work on a solution
                        for the problem, software cannot (unless we go into AI of some form).

                        Technically, this is inevitable and no other, more specialized
                        interface will help you, because if a Web service does not implement
                        some service.search() anymore the SOAP call will also fail and no WSDL
                        will prevent that. This is just the nature of binding the components
                        at runtime and not at compile time (as you would in a non-networked
                        application).

                        The problem is at the business level though because the WSDL specifies
                        a contract that defines the search method to be there and if you SOAP
                        call fails, you can take the WSDL and the stack trace, run to your
                        service provider and say: "Where's that method you *promised*?").

                        With REST, there is (deliberately) no such contract and the client's
                        expectation that there will be a search resource is based on
                        observation and trust and on some cloud-level based knowledge about
                        the overall kind of the interaction.

                        From the service owner perspective it is also an interesting
                        question, how a developer would know if he could take away the search
                        resource. After all, there is no contract to look at that would make
                        clear what the client expectations really are. IOW, if you are in
                        charge of evolving the service, you should have a pretty clear source
                        that tells you what you can change and what you cannot change. This is
                        rather easy on the media type level but it is also the combination of
                        hypermedia sematics in use that matter. "Are my clients 'licensed' to
                        assume the presence of that Atom extension or are they not? Well, we
                        never told them we'd never take it away so we can drop it at any time,
                        right?"

                        One approach to all this is probably to simply state that a service
                        will never evolve in an incompatible way (e.g. "we'll never remove
                        anything") and if it has to be incompatible, there'll just be a new
                        service.

                        Now, I am not trying to be enterprisey and ride the 'oh, inside the
                        enetrpsi there are the hard problems' horse, but 'follow your nose'
                        just does not provide the specifics that managers and lawyers (usually
                        rightly so) demand.

                        What is particulary interesting is that IMHO there is the danger of,
                        in the usual attempt to escape this situation, there is far too much
                        coupling put into the descriptive documents and many of REST's
                        advantages lost (see interface docs for example that list the URIs of
                        the resources to use, what formats to expect and which HTTP return
                        codes - and what they mean(!) in the service context).

                        So, balance is really important.

                        Jan



























                        > They don't seem to be needed in the human web. Sure you may need to
                        > document the representation formats -- the media type and the
                        > extensions and rels necessary to use the service. But its things
                        > like guarantees about what "kinds of state transitions" are
                        > available that I question. I'm not sure that the "inevitable
                        > assumptions" you refer to are necessary. Maybe I'm reading too much
                        > into what you mean by that though, but it seems to be more that what
                        > normally constitutes the uniform interface. Maybe I need more
                        > clarification on what you think would be in this contract.
                        > Regards,
                        >
                        > Andrew
                        >
                        >
                        >
                        >
                        > ------------------------------------
                        >
                        > Yahoo! Groups Links
                        >
                        >
                        >

                        --------------------------------------
                        Jan Algermissen

                        Mail: algermissen@...
                        Blog: http://algermissen.blogspot.com/
                        Home: http://www.jalgermissen.com
                        --------------------------------------
                      • Jan Algermissen
                        ... WTF??? ... Jan ... Jan Algermissen Mail: algermissen@acm.org Blog: http://algermissen.blogspot.com/ Home: http://www.jalgermissen.com
                        Message 11 of 25 , Nov 6, 2009
                          On Nov 6, 2009, at 4:58 PM, Jan Algermissen wrote:

                          > enetrpsi

                          WTF???

                          > 'enetrpsi' => 'enterprise' of course :-)

                          Jan



                          --------------------------------------
                          Jan Algermissen

                          Mail: algermissen@...
                          Blog: http://algermissen.blogspot.com/
                          Home: http://www.jalgermissen.com
                          --------------------------------------
                        • Will Hartung
                          ... I d reframe this and say such descriptions snapshot the state of a services implementation/API (version it, if you will). In theory, the service can
                          Message 12 of 25 , Nov 6, 2009
                            On Thu, Nov 5, 2009 at 5:16 AM, Jan Algermissen <algermissen1971@...> wrote:

                            > Occasionally demand is heard for service descriptions for services in
                            > RESTful systems. Clearly, such descriptions are contrary to REST's
                            > evolvability goals because any prescriptive information about the
                            > server limits its desired evolvability.

                            I'd reframe this and say such descriptions "snapshot" the state of a
                            services implementation/API (version it, if you will). In theory, the
                            service can still evolve from this base, as long as it doesn't violate
                            the contract as is. So, yes, technically it limits evolvability (you
                            can't go "backwards", for example), but I don't think it necessarily
                            kills any change whatsoever.

                            > One can put some amount of flexibility into a machine client, but it
                            > is inevitable that at some point assumptions end up in a place (source
                            > code, configuration) that will cause runtime failure when the
                            > assumptions about the server turn out to be wrong.

                            I think all clients are implicitly rigid. A flexible client is one
                            that is compensating for an imprecise specification. It's hard to
                            imagine any client able to inately adopt new functionality on the fly.
                            I should say, able to adopt any new functionality that the client
                            isn't aware of on the fly. It's possible that a client can leverage
                            functionality newly provided by the service, but that's driven by the
                            service surfacing functions that the client is already aware of. And I
                            won't explore client "plugins" or anything of that nature, it's not
                            germane.

                            > This is not so much of a problem in contexts, where budget and legal
                            > issues are of minor importance (e.g. when I do some fun-coding to
                            > interact with Amazon's APIs) but as soon as you pay serious amounts
                            > for the use of an API or when liability issues are involved things are
                            > different.
                            >
                            > What is necessary I think is a way to describe services that meets the
                            > following objectives:
                            >
                            > 1. **Only** describe/define those aspects of the provided
                            > service that constitute an inevitable coupling of
                            > client and server anyway. For example: if a client
                            > is programmed to use a search, the service provider
                            > must assure that the search will remain available
                            > during the agreed upon service lifetime.
                            >
                            > 2. Use a means of description that is formal enough to
                            > serve as the basis for legal contracts (e.g. SLAs).
                            >
                            > 3. Make that means of description standard/mainstream
                            > enough to avoid that everybody is forced to reinvent
                            > the wheel[1]

                            Seems to me that Steve was really banging on the "machine
                            enforcability" of the contract that you're talking about (thus his
                            continued references to WS-* and BPEL (I'm not familiar enough with
                            BPEL to know how it can be as specific as what he was looking for in
                            all of the scenarios he presented).

                            Everything else, is lawyers and weasel words, regardless of the format
                            of the specification, whether it's RFC format, post it notes, napkin
                            drawings, or what.

                            Having recently been doing work with the IHE Technical Specification
                            (which are robust, but imperfect and range from crystal clear to dark
                            as mud), my favorite attribute is the fact that all of the lines of
                            the specification are numbered (every 5 lines there's a notation in
                            the margin), which makes pointing out answers to specification
                            questions very easy (see doc XYZ, line 123).

                            > These are the aspects I think should be addressed in such definitions:
                            >
                            > 1. General client obligations
                            > This section would cover the base set of media types,
                            > link relations, etc. to be understood by the client.
                            >
                            > 2. General server commitments
                            > The description can be simplified and reduced if the
                            > server makes general commitments such as 'resources
                            > that are known by the client to be collections of items
                            > will always at least be available as application/atom+xml
                            >
                            > 3. General availability of certain state transitions
                            > A search resource for example can be defined to be available
                            > to the client independent of the current application state.
                            > IOW, the search resource will always be 'announced' as
                            > part of the initial service documents or, if none are used
                            > it would mean that the search would be available to the
                            > client from any received response (e.g. via Link header)
                            >
                            > 4. Availability of certain goals in certain application states
                            > If a client does a search in an online shop there is an
                            > expectation to being able to place an order afterwards.
                            > Such an expectation would be backed up by this section. A
                            > way to view this is as a dependency tree of goals (after
                            > item search can come purchase).

                            "General" here is the killer word. There should be nothing general
                            about it. These should all be specific, and documented. There are no
                            "assumptions". That's likely the complaint.

                            For example, look at all the assumptions that surround REST in the
                            first place. "Oh, it's just HTTP, I know HTTP..." and you get...POX
                            over HTTP or something else.

                            Something like "Search" can be a documented entry point in to the
                            system. Otherwise, it's a URI provided in payloads that the client can
                            follow. The specification may well be that a client must hit the
                            EntryPoint resource for the overall system, and follow the "Search"
                            link relation if they want to search.

                            "Availability of Certain Goals" would be, IMHO entry points in the
                            system. That is, URIs that are specifically documented and SLA'd to be
                            "always available". But if someone wants to order after a search, then
                            there is likely a defined link in the payload to create such an order
                            from the search results. Otherwise, the client can simply POST to the
                            /order resource with the proper payload, as documented in the
                            specification as an entry point, a point that can be hit directly, as
                            documented, rather than followed.

                            To clarify what I mean by that, there has always been a discussion as
                            to the lifespan of a URI. It's easy to argue that the link with the
                            "next" rel on a search result is likely to be a pretty temporal link.
                            The link itself can easily have a very limited lifespan, especially
                            the expectation that it returns anything meaningful. This because
                            there is little intent that a client would persist this link long
                            term. If you wanted to go to the next group of a search result, you
                            should follow the next-rel link.

                            But an external entry point is one that is likely to be "hard coded"
                            in to a client, is likely to be templated, and not necessarily opaque.
                            Because clients have to have some way to get started, and ideally they
                            don't all have to start at the "home page" and follow rels for every
                            transaction.

                            >
                            > 5. Availability of certain media types, link relations,
                            > extensions There must be a means for the server to tell the
                            > client which media types are available[2] and also a
                            > commitment that these (or at least one) will remain in use
                            > for a defined period of time.

                            This is all part of the SLA. I don't know if a server needs to
                            "publish" this information. I mean, you can have a /sla resource that
                            defines all of these things, I suppose. Does it need to be machine
                            interpretable?

                            But here's the nut.

                            The conflict is that with a REST system, the application should not be
                            driven by out-of-band information. It should not be making
                            assumptions, it should be working with the system as the service
                            exposes it to the client via request results from the pre-defined
                            entry points.

                            At an extreme view, that's what a specification is, out of band
                            information. Out of band information such as entry points, and link
                            relations. As more and more standardized media types and relations are
                            defined, and used, in theory, the "less" documentation and
                            specification is necessary, other than "Oh, go see spec XYZ, we follow
                            that.". But, then you get back to those assumptions about implementing
                            the spec properly.

                            Obviously SOME out of band information is necessary. The client needs
                            to know what the relationships mean so it can parse the request
                            properly to find links to actions.

                            Consider, an IRS Income Tax form. An IRS tax form is "reasonably"
                            documented form, with often descriptive rule summaries on the fields.
                            However, these field annotations are backed up by the "Form
                            Instructions", which go in to more detail about the form. Finally,
                            those instructions are backed by actual IRS law and procedure, which
                            is likely unusable by the layman.

                            So, of those three components: the Form (or in our case, the XSD of
                            the datatype), the Instructions, and the Law, which level of
                            documentation are we talking about here? Is the Law the SLA, the
                            Instructions the spec that gets sent to the developers by the BSA, and
                            the Form the structure the application uses to find where to put data
                            and links, an XSD for example?

                            Regards,

                            Will Hartung
                            (willh@...)
                          • Subbu Allamaraju
                            ... Sorry, but I think it is a flawed assertion to say that WS-* has a rigid interface description language built in which somehow makes it better. Just
                            Message 13 of 25 , Nov 6, 2009
                              >>
                              >>
                              >
                              > Sure prose is appropriate (never suggested otherwise). But just
                              > saying 'use prose' does not address 3. above. This was one of the
                              > points made by Steve Jones: given that WS-* has a rigid interface
                              > description language 'built in' while the use of REST means you have
                              > to come up with a means of describing interfaces yourself is a huge
                              > selling point for WS-*. Not that having such things as WSDL and BPEL
                              > is desireable from a networked systems point of view but when a non
                              > technical person has to make a business decision about WS-* vs REST,
                              > the latter is more likely to 'loose' if you first have to come up
                              > with a style for documenting the interfaces. And even worse would be
                              > the position of 'Nah, you don't need that. Just let everyone write
                              > it up'.


                              Sorry, but I think it is a flawed assertion to say that "WS-* has a
                              rigid interface description language 'built in'" which somehow makes
                              it better. Just because it has been sold like that does not make it
                              true. I would love to see a developer who wrote a client application
                              by just looking at the WSDL, or a business person who was not asked a
                              single clarification about some operation or a field is supposed to
                              work.

                              Subbu
                            • Andrew Wahbe
                              On Fri, Nov 6, 2009 at 10:58 AM, Jan Algermissen ... Ok so right out of the gate I have issues with this. Coding a client for a service seems unRESTful to
                              Message 14 of 25 , Nov 6, 2009
                                On Fri, Nov 6, 2009 at 10:58 AM, Jan Algermissen
                                <algermissen1971@...> wrote:
                                >
                                > On Nov 6, 2009, at 3:36 PM, wahbedahbe wrote:
                                >
                                >> --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...>
                                >> wrote:
                                >>>
                                >>>
                                >>> On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:
                                >>>
                                >>>> There are a lot of assumptions here about the limitations of machine
                                >>>> to machine RESTful interaction. I have never seen any proof of these
                                >>>> limitations. It just seems that because the general REST community
                                >>>> can't figure out how to design good media types for machine to
                                >>>> machine interaction, the consensus is that it isn't possible.
                                >>>
                                >>> I did not say that at all. Of course machine to machine RESTful
                                >>> systems are possible (e.g. AtomPub). I was talking about inevitable
                                >>> assumptions the client has to make that manifest itself in code or
                                >>> configuration of and how to document these such that
                                >>>
                                >>> - no unnecessary coupling is created by the documentation
                                >>>  (as is by many of the documentations of the so called REST
                                >>>  interfaces on the Web)
                                >>> - the style of documentation will be accepted by e.g.
                                >>>  the legal department
                                >>>
                                >>> Jan
                                >>>
                                >>
                                >> Right, but it's the assumption that these out-of-band contracts are needed
                                >> is what I'm questioning.
                                >
                                > Suppose you are coding a client for service that lets you search stuff and
                                > then do something with it (e.g. update). Your client code will inevitably
                                > contain the 'invocation' of the search (e.g. GET request to search
                                > resource). And this is based on the expectation that the search resource
                                > will be there (== being discoverable).

                                Ok so right out of the gate I have issues with this. "Coding a client
                                for a service" seems unRESTful to me. Firefox is not coded for Google,
                                Facebook or Amazon. It is coded for URIs, HTTP and HTML (and HTML's
                                "friends" CSS, Javascript etc.). Your client will only have code that
                                has a notion of search invocation if it is inherent in the media type
                                (including extensions and relations). But that is not necessary for
                                search to work. The client could be performing a search without
                                "knowing" it, because a combination of the media type, the current
                                representation/state, and the client disposition and/or client side
                                events have caused the search link to be followed. This is what
                                happens when I use my browser to do a Google search. I don't see why
                                this can't be the case for media types other than HTML (and it
                                certainly would be for VoiceXML and CCXML).

                                > If the service does not provide the
                                > search resource anymore the client will break (if you code it to expect that
                                > there is a search resource and sudden;y there is none what else could the
                                > code do?). Humans can work on a solution for the problem, software cannot
                                > (unless we go into AI of some form).

                                I'm not sure what is "broken" here. The service seems broken, but I'm
                                not sure if the client is broken -- you should be able to point it at
                                any other service that supports the client's media type(s) and it
                                should still work just fine. Or is the service just changed so that
                                the search step is not required anymore? If the service is still
                                accomplishing a useful goal within the bounds of the client's media
                                type, things still seem ok. If the service is now not doing something
                                useful -- well that is a service implementation issue. If it's still
                                working within the bounds of the media type then it is not a technical
                                issue with the contract between client and service _software_. It is
                                more of an issue between the operator of the client and the operator
                                of the service -- maybe I'm splitting hairs here but it seems to be
                                different than what you are describing. And more importantly doesn't
                                seem to have any differences in the machine-to-machine vs.
                                human-to-machine contexts. i.e. if Amazon stopped selling books, it
                                would trip up a human too. The solution -- go to a different start
                                URI -- applies in both contexts as well. And Firefox is not going to
                                figure out what alternate URI to use just as a machine-driven client
                                will not.

                                If the service started spitting back representations that did not
                                conform to the client's media type. Then I think you can say that the
                                software contract is broken (especially if the client is setting it's
                                accept headers properly). But this again equally trips up machine
                                driven and human driven client software.

                                >
                                > Technically, this is inevitable and no other, more specialized interface
                                > will help you, because if a Web service does not implement some
                                > service.search() anymore the SOAP call will also fail and no WSDL will
                                > prevent that. This is just the nature of binding the components at runtime
                                > and not at compile time (as you would in a non-networked application).
                                >
                                > The problem is at the business level though because the WSDL specifies a
                                > contract that defines the search method to be there and if you SOAP call
                                > fails, you can take the WSDL and the stack trace, run to your service
                                > provider and say: "Where's that method you *promised*?").
                                >

                                Right. So in REST, the software contract is more "client specific".
                                i.e. the client supports a known media type and the service targets
                                that media type and all clients that support it. So the "missing
                                method" equivalent would be somehow not conforming to the media type
                                supported by the client. And if search capability was something that
                                had to be in every document of that media type then you get the same
                                sort of contract. But often that is not the case (it isn't the case
                                with HTML and lots of other media types anyways).

                                Instead the service is publishing a URI and saying "somewhere behind
                                this URI, search is going to happen". But that is a contract between
                                the client operator and the service operator about the semantics of
                                the service, not the interface. The WSDL equivalent might be the case
                                where the search method is there but it doesn't provide search
                                semantics (e.g. it always spits back the same results no matter what
                                the search terms are).


                                > With REST, there is (deliberately) no such contract and the client's
                                > expectation that there will be a search resource is based on observation and
                                > trust and on some cloud-level based knowledge about the overall kind of the
                                > interaction.
                                >
                                > From the service owner perspective it is also an interesting question, how a
                                > developer would know if he could take away the search resource. After all,
                                > there is no contract to look at that would make clear what the client
                                > expectations really are. IOW, if you are in charge of evolving the service,
                                > you should have a pretty clear source that tells you what you can change and
                                > what you cannot change. This is rather easy on the media type level but it
                                > is also the combination of hypermedia sematics in use that matter. "Are my
                                > clients 'licensed' to assume the presence of that Atom extension or are they
                                > not? Well, we never told them we'd never take it away so we can drop it at
                                > any time, right?"
                                >
                                > One approach to all this is probably to simply state that a service will
                                > never evolve in an incompatible way (e.g. "we'll never remove anything") and
                                > if it has to be incompatible, there'll just be a new service.
                                >
                                > Now, I am not trying to be enterprisey and ride the 'oh, inside the enetrpsi
                                > there are the hard problems' horse, but 'follow your nose' just does not
                                > provide the specifics that managers and lawyers (usually rightly so) demand.
                                >
                                > What is particulary interesting is that IMHO there is the danger of, in the
                                > usual attempt to escape this situation, there is far too much coupling put
                                > into the descriptive documents and many of REST's advantages lost (see
                                > interface docs for example that list the URIs of the resources to use, what
                                > formats to expect and which HTTP return codes - and what they mean(!) in the
                                > service context).
                                >
                                > So, balance is really important.
                                >
                                > Jan
                                >

                                So here's an observation: In the web (and in the VoiceXML/CCXML
                                world), extension support and in general, media type evolution is
                                driven by clients not services. In the machine-driven-REST world, the
                                trend seems to be the opposite. That means service interfaces are
                                "service specific" (e.g. the media type is service-specific or
                                includes service-specific extensions, namespaces or relations). That
                                means coupling. That means that you don't get the full advantages of
                                REST. If I had to point to a constraint being violated, I'd say it was
                                "Self-Descriptive Messages". I don't see how a message can be
                                self-descriptive if it is in a service-specific format. To me that is
                                a key part of using "standard" media types -- the media type exists
                                outside of the context of your service. But I know a lot of folks have
                                different interpretations of what "standard" means in the context of
                                REST. The differences are subtle but I think the implications are
                                huge.

                                Andrew
                              • Jan Algermissen
                                ... Don t get me wrong: I am not saying that it is better. I am just saying that the WSDL serves a (perceived) need of the people in charge of assigning people
                                Message 15 of 25 , Nov 6, 2009
                                  On Nov 6, 2009, at 8:29 PM, Subbu Allamaraju wrote:

                                  >
                                  >>>
                                  >>>
                                  >>
                                  >> Sure prose is appropriate (never suggested otherwise). But just
                                  >> saying 'use prose' does not address 3. above. This was one of the
                                  >> points made by Steve Jones: given that WS-* has a rigid interface
                                  >> description language 'built in' while the use of REST means you have
                                  >> to come up with a means of describing interfaces yourself is a huge
                                  >> selling point for WS-*. Not that having such things as WSDL and BPEL
                                  >> is desireable from a networked systems point of view but when a non
                                  >> technical person has to make a business decision about WS-* vs REST,
                                  >> the latter is more likely to 'loose' if you first have to come up
                                  >> with a style for documenting the interfaces. And even worse would be
                                  >> the position of 'Nah, you don't need that. Just let everyone write
                                  >> it up'.
                                  >
                                  >
                                  > Sorry, but I think it is a flawed assertion to say that "WS-* has a
                                  > rigid interface description language 'built in'" which somehow makes
                                  > it better.

                                  Don't get me wrong: I am not saying that it is better. I am just
                                  saying that the WSDL serves a (perceived) need of the people in charge
                                  of assigning people like us the budget.

                                  And I am saying that it is very easy to actually build more coupling
                                  into prose definitions of REST services than is necessary.


                                  Jan




                                  > Just because it has been sold like that does not make it
                                  > true. I would love to see a developer who wrote a client application
                                  > by just looking at the WSDL, or a business person who was not asked a
                                  > single clarification about some operation or a field is supposed to
                                  > work.






                                  >
                                  > Subbu
                                  >
                                  >
                                  > ------------------------------------
                                  >
                                  > Yahoo! Groups Links
                                  >
                                  >
                                  >

                                  --------------------------------------
                                  Jan Algermissen

                                  Mail: algermissen@...
                                  Blog: http://algermissen.blogspot.com/
                                  Home: http://www.jalgermissen.com
                                  --------------------------------------
                                • Jan Algermissen
                                  ... Ok, yes. I should have made the distinction between the user agent and the program that makes use of it. At least this is my mental model: you have a
                                  Message 16 of 25 , Nov 6, 2009
                                    On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:

                                    > On Fri, Nov 6, 2009 at 10:58 AM, Jan Algermissen
                                    > <algermissen1971@...> wrote:
                                    >>
                                    >> On Nov 6, 2009, at 3:36 PM, wahbedahbe wrote:
                                    >>
                                    >>> --- In rest-discuss@yahoogroups.com, Jan Algermissen
                                    >>> <algermissen1971@...>
                                    >>> wrote:
                                    >>>>
                                    >>>>
                                    >>>> On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:
                                    >>>>
                                    >>>>> There are a lot of assumptions here about the limitations of
                                    >>>>> machine
                                    >>>>> to machine RESTful interaction. I have never seen any proof of
                                    >>>>> these
                                    >>>>> limitations. It just seems that because the general REST community
                                    >>>>> can't figure out how to design good media types for machine to
                                    >>>>> machine interaction, the consensus is that it isn't possible.
                                    >>>>
                                    >>>> I did not say that at all. Of course machine to machine RESTful
                                    >>>> systems are possible (e.g. AtomPub). I was talking about inevitable
                                    >>>> assumptions the client has to make that manifest itself in code or
                                    >>>> configuration of and how to document these such that
                                    >>>>
                                    >>>> - no unnecessary coupling is created by the documentation
                                    >>>> (as is by many of the documentations of the so called REST
                                    >>>> interfaces on the Web)
                                    >>>> - the style of documentation will be accepted by e.g.
                                    >>>> the legal department
                                    >>>>
                                    >>>> Jan
                                    >>>>
                                    >>>
                                    >>> Right, but it's the assumption that these out-of-band contracts
                                    >>> are needed
                                    >>> is what I'm questioning.
                                    >>
                                    >> Suppose you are coding a client for service that lets you search
                                    >> stuff and
                                    >> then do something with it (e.g. update). Your client code will
                                    >> inevitably
                                    >> contain the 'invocation' of the search (e.g. GET request to search
                                    >> resource). And this is based on the expectation that the search
                                    >> resource
                                    >> will be there (== being discoverable).
                                    >
                                    > Ok so right out of the gate I have issues with this. "Coding a client
                                    > for a service" seems unRESTful to me. Firefox is not coded for Google,
                                    > Facebook or Amazon. It is coded for URIs, HTTP and HTML (and HTML's
                                    > "friends" CSS, Javascript etc.).

                                    Ok, yes. I should have made the distinction between the 'user agent'
                                    and the program that makes use of it. At least this is my mental
                                    model: you have a library that implements all the specs that make
                                    sense to implement (meaning: not only the ones for this service) and
                                    this piece is equivalent to the browser. Then, you need some piece of
                                    code that uses the user agent to interact with the service (or the Web
                                    for that matter). This piece of code is equivalent to the human being.
                                    Inside this code (or its configuration) one must manifest some
                                    expectations (e.g. that the search resource is there so the user agent
                                    can carry out the search and hand the result back to the program.

                                    If you want to get rid of that assumption you'd have to come up with a
                                    way for the service to actually drive the client program (like a GUI
                                    app is driven by the GUI). However, this does not work because the
                                    client is a state machine on its own and cannot be entirely driven by
                                    the hyper,edia received from the server. At some point there must be
                                    'invocations of goals' by the client side program.


                                    > Your client will only have code that
                                    > has a notion of search invocation if it is inherent in the media type
                                    > (including extensions and relations). But that is not necessary for
                                    > search to work. The client could be performing a search without
                                    > "knowing" it, because a combination of the media type, the current
                                    > representation/state, and the client disposition and/or client side
                                    > events have caused the search link to be followed. This is what
                                    > happens when I use my browser to do a Google search. I don't see why
                                    > this can't be the case for media types other than HTML (and it
                                    > certainly would be for VoiceXML and CCXML).

                                    Yes, great model. But what is driving the whole thing? With the
                                    browser it is the human being that drives the interaction because she
                                    e.g. wants to buy a book. In the machine world you need a process that
                                    initiates a goal and this goal includes assumptions.


                                    >
                                    >> If the service does not provide the
                                    >> search resource anymore the client will break (if you code it to
                                    >> expect that
                                    >> there is a search resource and sudden;y there is none what else
                                    >> could the
                                    >> code do?). Humans can work on a solution for the problem, software
                                    >> cannot
                                    >> (unless we go into AI of some form).
                                    >
                                    > I'm not sure what is "broken" here. The service seems broken, but I'm
                                    > not sure if the client is broken -- you should be able to point it at
                                    > any other service that supports the client's media type(s) and it
                                    > should still work just fine.

                                    Yeah - and this is precisely what you cannot utter in a room full with
                                    the guys that assign the budget or care about the company being sued.
                                    Would you pay for Google's API and then, if part of the service
                                    disappears just go of to some other service on the Web?


                                    > Or is the service just changed so that
                                    > the search step is not required anymore? If the service is still
                                    > accomplishing a useful goal within the bounds of the client's media
                                    > type, things still seem ok.

                                    Yes, this sort of magic can be coded into the user agent component and
                                    this is what enables the evolvability of the components without the
                                    need for bringing all the devs in a room all the time.

                                    > If the service is now not doing something
                                    > useful -- well that is a service implementation issue. If it's still
                                    > working within the bounds of the media type then it is not a technical
                                    > issue with the contract between client and service _software_. It is
                                    > more of an issue between the operator of the client and the operator
                                    > of the service -- maybe I'm splitting hairs here but it seems to be
                                    > different than what you are describing. And more importantly doesn't
                                    > seem to have any differences in the machine-to-machine vs.
                                    > human-to-machine contexts. i.e. if Amazon stopped selling books, it
                                    > would trip up a human too. The solution -- go to a different start
                                    > URI -- applies in both contexts as well.

                                    Right. But as said above: there are a substantial number of people
                                    that won't buy into it. And often rightly so because when you assign
                                    budget to something. It is all about documenting the assumptions that
                                    might break. I do not see media types to be the means where this can
                                    be done. Especialy not when a service uses a combination of hypermedia
                                    semantics. Or how would you express that a service pronises to use a
                                    certain Atom extension? You could if you'd define application/myatom
                                    and make the extension mandatory but this obviously breaks
                                    orthogonality.


                                    > And Firefox is not going to
                                    > figure out what alternate URI to use just as a machine-driven client
                                    > will not.
                                    >
                                    > If the service started spitting back representations that did not
                                    > conform to the client's media type. Then I think you can say that the
                                    > software contract is broken (especially if the client is setting it's
                                    > accept headers properly). But this again equally trips up machine
                                    > driven and human driven client software.

                                    Yes. So, how does a service say what media types the client may safely
                                    expect?


                                    >
                                    >>
                                    >> Technically, this is inevitable and no other, more specialized
                                    >> interface
                                    >> will help you, because if a Web service does not implement some
                                    >> service.search() anymore the SOAP call will also fail and no WSDL
                                    >> will
                                    >> prevent that. This is just the nature of binding the components at
                                    >> runtime
                                    >> and not at compile time (as you would in a non-networked
                                    >> application).
                                    >>
                                    >> The problem is at the business level though because the WSDL
                                    >> specifies a
                                    >> contract that defines the search method to be there and if you SOAP
                                    >> call
                                    >> fails, you can take the WSDL and the stack trace, run to your service
                                    >> provider and say: "Where's that method you *promised*?").
                                    >>
                                    >
                                    > Right. So in REST, the software contract is more "client specific".
                                    > i.e. the client supports a known media type and the service targets
                                    > that media type and all clients that support it. So the "missing
                                    > method" equivalent would be somehow not conforming to the media type
                                    > supported by the client. And if search capability was something that
                                    > had to be in every document of that media type then you get the same
                                    > sort of contract. But often that is not the case (it isn't the case
                                    > with HTML and lots of other media types anyways).
                                    >
                                    > Instead the service is publishing a URI and saying "somewhere behind
                                    > this URI, search is going to happen".

                                    So, how does it say that?

                                    > But that is a contract between
                                    > the client operator and the service operator about the semantics of
                                    > the service, not the interface.

                                    Well, yes. It is all about how this contract is best established and
                                    written.

                                    > The WSDL equivalent might be the case
                                    > where the search method is there but it doesn't provide search
                                    > semantics (e.g. it always spits back the same results no matter what
                                    > the search terms are).
                                    >
                                    >
                                    >> With REST, there is (deliberately) no such contract and the client's
                                    >> expectation that there will be a search resource is based on
                                    >> observation and
                                    >> trust and on some cloud-level based knowledge about the overall
                                    >> kind of the
                                    >> interaction.
                                    >>
                                    >> From the service owner perspective it is also an interesting
                                    >> question, how a
                                    >> developer would know if he could take away the search resource.
                                    >> After all,
                                    >> there is no contract to look at that would make clear what the client
                                    >> expectations really are. IOW, if you are in charge of evolving the
                                    >> service,
                                    >> you should have a pretty clear source that tells you what you can
                                    >> change and
                                    >> what you cannot change. This is rather easy on the media type level
                                    >> but it
                                    >> is also the combination of hypermedia sematics in use that matter.
                                    >> "Are my
                                    >> clients 'licensed' to assume the presence of that Atom extension or
                                    >> are they
                                    >> not? Well, we never told them we'd never take it away so we can
                                    >> drop it at
                                    >> any time, right?"
                                    >>
                                    >> One approach to all this is probably to simply state that a service
                                    >> will
                                    >> never evolve in an incompatible way (e.g. "we'll never remove
                                    >> anything") and
                                    >> if it has to be incompatible, there'll just be a new service.
                                    >>
                                    >> Now, I am not trying to be enterprisey and ride the 'oh, inside the
                                    >> enetrpsi
                                    >> there are the hard problems' horse, but 'follow your nose' just
                                    >> does not
                                    >> provide the specifics that managers and lawyers (usually rightly
                                    >> so) demand.
                                    >>
                                    >> What is particulary interesting is that IMHO there is the danger
                                    >> of, in the
                                    >> usual attempt to escape this situation, there is far too much
                                    >> coupling put
                                    >> into the descriptive documents and many of REST's advantages lost
                                    >> (see
                                    >> interface docs for example that list the URIs of the resources to
                                    >> use, what
                                    >> formats to expect and which HTTP return codes - and what they
                                    >> mean(!) in the
                                    >> service context).
                                    >>
                                    >> So, balance is really important.
                                    >>
                                    >> Jan
                                    >>
                                    >
                                    > So here's an observation: In the web (and in the VoiceXML/CCXML
                                    > world), extension support and in general, media type evolution is
                                    > driven by clients not services. In the machine-driven-REST world, the
                                    > trend seems to be the opposite. That means service interfaces are
                                    > "service specific" (e.g. the media type is service-specific or
                                    > includes service-specific extensions, namespaces or relations). That
                                    > means coupling. That means that you don't get the full advantages of
                                    > REST. If I had to point to a constraint being violated, I'd say it was
                                    > "Self-Descriptive Messages". I don't see how a message can be
                                    > self-descriptive if it is in a service-specific format. To me that is
                                    > a key part of using "standard" media types -- the media type exists
                                    > outside of the context of your service.

                                    Yes, that is a very, very good way to see it. When enterprises engage
                                    in a REST effort, they should not worry about defining services (but
                                    it is what everybody immediately does :-) The should form a central
                                    board (like the IETF) and get their media types sorted out. At least
                                    enough to get the project rolling. If you do the types as you need
                                    them for the services you won't get the generalization level right.
                                    (You should of course let the envisioned services inspire your central
                                    effort). So, to repeat your very true words:

                                    > "the media type exists outside of the context of your service."



                                    > But I know a lot of folks have
                                    > different interpretations of what "standard" means in the context of
                                    > REST. The differences are subtle but I think the implications are
                                    > huge.

                                    Yes and yes.

                                    Jan


                                    >
                                    > Andrew

                                    --------------------------------------
                                    Jan Algermissen

                                    Mail: algermissen@...
                                    Blog: http://algermissen.blogspot.com/
                                    Home: http://www.jalgermissen.com
                                    --------------------------------------
                                  • wahbedahbe
                                    ... A CCXML document describes a state machine for processing events raised up to the client. For each type of event fired, the document describes the
                                    Message 17 of 25 , Nov 6, 2009
                                      --- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...> wrote:
                                      >
                                      >
                                      > On Nov 6, 2009, at 6:45 AM, wahbedahbe wrote:
                                      >
                                      > > I've been encouraging folks on this list to look at CCXML for a long
                                      > > time, but as far as I know I haven't convinced anyone to spend the
                                      > > time. Hey -- maybe CCXML isn't RESTful after all; it certainly has a
                                      > > different flavor than most of the media types coming from the REST
                                      > > community. I'd love to get all of your feedback; maybe I'm missing
                                      > > something. But if it isn't then perhaps the as yet to be formally
                                      > > defined style behind CCXML is a good alternative to REST for machine
                                      > > to machine interaction. It certainly seems to have many of the
                                      > > properties most readers of this list are looking for.
                                      >
                                      >
                                      > From the TR: "A CCXML session begins with the execution of a CCXML
                                      > document."
                                      >
                                      > Now, my understanding might be wrong because I dod not have the time
                                      > to put my head into the spec, but the above quote sounds a lot like
                                      > that the coordination between components in CCXML is achieved by
                                      > passing code (executable documents) around. To be RESTful the
                                      > coordination should be achieved by passing representations of state
                                      > around.
                                      >
                                      > Can you provide us with an example of a typical interaction?
                                      >
                                      > Jan

                                      A CCXML document describes a state machine for processing events raised up to the client. For each type of event fired, the document describes the transition -- the next state as well as the "actions" to be taken on the transition. This could be events sent back down to the underlying platform, the execution of some javascript or it could describe a page transition.

                                      The entire service is composed of a set of mini-state machine documents. A GET or a POST can be used to transition from document to document. Javascript variables can be marshalled into the query string of a GET or the body of a POST much like an HTML form (though the syntax is very different as this is not a form abstraction). Also, there is no PUT or DELETE support like in (current) HTML.

                                      Page transitions are kind of interesting in CCXML because they are broken into two steps. First, a <fetch> tag is executed on a page transition that tells the client to perform the GET or POST. An event is fired when the request is complete and the page is parsed and ready to go. A <goto> tag can then be executed to complete the transition. This model is used to allow the state machine to continue handling events during page transitions. Ancillary script resources can be handled in a similar way with <fetch> and <script> (though <script> can also just use a src attribute in which case the script is fetched and parsed when the parent ccxml document is first being prepared for execution).

                                      In HTML, a good portion of the javascript processing is focused on handling events. This is the same in CCXML, but here the scripts do not modify a DOM -- the ccxml markup describes the state machine being executed and a state machine that changes as it executes would likely make most developers heads explode! The objects exposed to the script are objects controlled by the client -- calls, conferences and dialogs (an automated phone system session, usually implemented in VoiceXML -- http://www.w3.org/TR/voicexml20/). I think perhaps the window object would be a good HTML analog.

                                      The events in ccxml are mostly describing changes to these objects (though some are related to the document execution, e.g. "your <fetch> completed"). So an event might signify that caller A hung up. The messages/events sent down to the platform on a state transition are primarily used to invoke methods on those objects. You get an event back when your method completed. e.g. You send a message to join callers A and B together so they can hear each other and get an event back when the join completed. This is not implemented as simple javascript calls as asynchrony is important so that the state machine is never blocked. You could use asynchronous javascript functions I suppose, but the event handling is the primary purpose of the document format so the markup expresses event handling as much as possible.

                                      That's sort of a long intro to CCXML. Sorry about that, but I thought it was necessary to establish a bit of common ground on the format before answering your questions. Some of the simple examples in the spec might be worth a quick read at this point: http://www.w3.org/TR/ccxml/#SimpleExamples

                                      So back to your questions...

                                      Is a CCXML document executable? Yes. But I'd argue that an HTML document is too. It's funny, but when people look at HTML through REST-colored glasses they seem to completely miss all of the event handling going on. A huge portion of the content of an HTML document is focused on handling input events. Even if you strip out the javascript and the on* attributes, the markup is still telling the browser how to handle input events. The <a> element tells the browser what to do when the presentation of the enclosed text is "activated" (e.g. clicked). The <form> and <input> elements tell the browser how to present controls with specific interaction semantics.

                                      Maybe it's my own background in VoiceXML/CCXML but I've always thought of markup as "executable" -- a mini-program in a declarative form. The declarative format makes the program semantics more visible and allows tools and spiders to deal with the markup more easily to provide "secondary" types of document processing. e.g. what TBL describes as the Principle of Least Power: http://www.w3.org/DesignIssues/Principles.html

                                      To me "code on demand" means adding non-declarative executable content into the mix to provide functionality beyond what is expressable in declarative form at the expense of visibility. So because CCXML, VoiceXML, or event HTML markup can be seen as "executable" does not instantly imply code-on-demand (well, CCXML is unnecessarily tied to Javascript, but you could envision an equivalent language that didn't require it).

                                      Now, can you view a CCXML document as a representation of resource state? I think so. Consider a Google Voice like service that allows a single phone number to be used to contact you at a number of alternate numbers (your home, office and cell phone) and send the call to voice mail if you don't answer any of them. A resource here might be a single user's settings for the service, specifying the phone numbers to try and in what order, the number of seconds to wait on each number before sending the call to voicemail, etc.

                                      The standard approach most REST practitioners would take here would be to cook up an XML or JSON format for this data and stick it behind a URI. The same XML/JSON would be served to say an Ajax interface for editing the data and to the system that actually implemented the call control service that tried to reach you.

                                      I consider this a non-self-descriptive message because it's using a service-specific, non-standard format. All clients would be bound to the service because they are bound to it's format. Instead, content negotiation should be used to represent the resource in a format specific to the requesting client. So serve the HTML page to view and edit the user's settings to a web browser and serve the CCXML state machine that represented those settings to the call control system. The CCXML state machine is a representation of those settings, just as the HTML web page is a representation. Here the clients support their native markup formats and are not bound to the service at all.

                                      If you've got this far in the email, then thanks for reading -- this was a lot longer than I anticipated, but hopefully it gets the idea across.
                                      Regards,

                                      Andrew
                                    • Jan Algermissen
                                      ... So (ideally and stretching the point): - services should only use media types understood by all clients - services should use as many hypermedia options
                                      Message 18 of 25 , Nov 6, 2009
                                        On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:

                                        >
                                        > So here's an observation: In the web (and in the VoiceXML/CCXML
                                        > world), extension support and in general, media type evolution is
                                        > driven by clients not services. In the machine-driven-REST world, the
                                        > trend seems to be the opposite. That means service interfaces are
                                        > "service specific" (e.g. the media type is service-specific or
                                        > includes service-specific extensions, namespaces or relations). That
                                        > means coupling. That means that you don't get the full advantages of
                                        > REST. If I had to point to a constraint being violated, I'd say it was
                                        > "Self-Descriptive Messages". I don't see how a message can be
                                        > self-descriptive if it is in a service-specific format. To me that is
                                        > a key part of using "standard" media types -- the media type exists
                                        > outside of the context of your service.

                                        So (ideally and stretching the point):

                                        - services should only use media types understood by all clients
                                        - services should use as many hypermedia 'options' as possible
                                        (so if a client does not find a particuar link etc. it can
                                        infer that the supporting application data does not exist.

                                        JAn



                                        > But I know a lot of folks have
                                        > different interpretations of what "standard" means in the context of
                                        > REST. The differences are subtle but I think the implications are
                                        > huge.
                                        >
                                        > Andrew
                                        >
                                        >
                                        > ------------------------------------
                                        >
                                        > Yahoo! Groups Links
                                        >
                                        >
                                        >

                                        --------------------------------------
                                        Jan Algermissen

                                        Mail: algermissen@...
                                        Blog: http://algermissen.blogspot.com/
                                        Home: http://www.jalgermissen.com
                                        --------------------------------------
                                      • Andrew Wahbe
                                        ... Well not quite. I don t think you can expect all clients to understand the same media types. I d say something more like: - services should use the media
                                        Message 19 of 25 , Nov 6, 2009
                                          On Fri, Nov 6, 2009 at 3:59 PM, Jan Algermissen <algermissen1971@...> wrote:
                                          >
                                          > On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:
                                          >
                                          >>
                                          >> So here's an observation: In the web (and in the VoiceXML/CCXML
                                          >> world), extension support and in general, media type evolution is
                                          >> driven by clients not services. In the machine-driven-REST world, the
                                          >> trend seems to be the opposite. That means service interfaces are
                                          >> "service specific" (e.g. the media type is service-specific or
                                          >> includes service-specific extensions, namespaces or relations). That
                                          >> means coupling. That means that you don't get the full advantages of
                                          >> REST. If I had to point to a constraint being violated, I'd say it was
                                          >> "Self-Descriptive Messages". I don't see how a message can be
                                          >> self-descriptive if it is in a service-specific format. To me that is
                                          >> a key part of using "standard" media types -- the media type exists
                                          >> outside of the context of your service.
                                          >
                                          > So (ideally and stretching the point):
                                          >
                                          > - services should only use media types understood by all clients
                                          > - services should use as many hypermedia 'options' as possible
                                          >  (so if a client does not find a particuar link etc. it can
                                          >  infer that the supporting application data does not exist.
                                          >
                                          > JAn
                                          >

                                          Well not quite. I don't think you can expect "all clients" to
                                          understand the same media types. I'd say something more like:
                                          - services should use the media types understood by the clients they
                                          are targeting.

                                          On the other point, I'm not sure what you mean by hypermedia 'options'.

                                          Andrew
                                        • mike amundsen
                                          Jan: - services should only use media types understood by all clients - services should use as many hypermedia options as possible (so if a client
                                          Message 20 of 25 , Nov 6, 2009
                                            Jan:

                                            <snip>
                                            - services should only use media types understood by all clients
                                            - services should use as many hypermedia 'options' as possible
                                            (so if a client does not find a particuar link etc. it can
                                            infer that the supporting application data does not exist.
                                            </snip>

                                            Servers can only make promises on any pre-published URIs and on
                                            media-types (including format, scheme, and semantics such as links and
                                            relation values).

                                            mca
                                            http://amundsen.com/blog/




                                            On Fri, Nov 6, 2009 at 15:59, Jan Algermissen <algermissen1971@...> wrote:
                                            >
                                            > On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:
                                            >
                                            >>
                                            >> So here's an observation: In the web (and in the VoiceXML/CCXML
                                            >> world), extension support and in general, media type evolution is
                                            >> driven by clients not services. In the machine-driven-REST world, the
                                            >> trend seems to be the opposite. That means service interfaces are
                                            >> "service specific" (e.g. the media type is service-specific or
                                            >> includes service-specific extensions, namespaces or relations). That
                                            >> means coupling. That means that you don't get the full advantages of
                                            >> REST. If I had to point to a constraint being violated, I'd say it was
                                            >> "Self-Descriptive Messages". I don't see how a message can be
                                            >> self-descriptive if it is in a service-specific format. To me that is
                                            >> a key part of using "standard" media types -- the media type exists
                                            >> outside of the context of your service.
                                            >
                                            > So (ideally and stretching the point):
                                            >
                                            > - services should only use media types understood by all clients
                                            > - services should use as many hypermedia 'options' as possible
                                            >   (so if a client does not find a particuar link etc. it can
                                            >   infer that the supporting application data does not exist.
                                            >
                                            > JAn
                                            >
                                            >
                                            >
                                            >> But I know a lot of folks have
                                            >> different interpretations of what "standard" means in the context of
                                            >> REST. The differences are subtle but I think the implications are
                                            >> huge.
                                            >>
                                            >> Andrew
                                            >>
                                            >>
                                            >> ------------------------------------
                                            >>
                                            >> Yahoo! Groups Links
                                            >>
                                            >>
                                            >>
                                            >
                                            > --------------------------------------
                                            > Jan Algermissen
                                            >
                                            > Mail: algermissen@...
                                            > Blog: http://algermissen.blogspot.com/
                                            > Home: http://www.jalgermissen.com
                                            > --------------------------------------
                                            >
                                            >
                                            >
                                            >
                                            >
                                            > ------------------------------------
                                            >
                                            > Yahoo! Groups Links
                                            >
                                            >
                                            >
                                            >
                                          • Jan Algermissen
                                            ... I meant that (ideally and stretching the point) services should make use of as much hypermedia as they can. If they know about foo links and if they can
                                            Message 21 of 25 , Nov 6, 2009
                                              On Nov 6, 2009, at 10:27 PM, Andrew Wahbe wrote:

                                              > On Fri, Nov 6, 2009 at 3:59 PM, Jan Algermissen <algermissen1971@...
                                              > > wrote:
                                              >>
                                              >>>
                                              >>
                                              >> So (ideally and stretching the point):
                                              >>
                                              >> - services should only use media types understood by all clients
                                              >> - services should use as many hypermedia 'options' as possible
                                              >> (so if a client does not find a particuar link etc. it can
                                              >> infer that the supporting application data does not exist.
                                              >>
                                              >> JAn
                                              >>
                                              >
                                              > Well not quite. I don't think you can expect "all clients" to
                                              > understand the same media types. I'd say something more like:
                                              > - services should use the media types understood by the clients they
                                              > are targeting.
                                              >
                                              > On the other point, I'm not sure what you mean by hypermedia
                                              > 'options'.

                                              I meant that (ideally and stretching the point) services should make
                                              use of
                                              as much hypermedia as they can. If they know about foo links and if
                                              they can
                                              provide a foo link they should do so.
                                              So when clients do not find a foo link they can reasonably 'believe'
                                              that
                                              the server cannot provide one.

                                              (But this is just strectching the point and mumbling)

                                              Jan


                                              >
                                              > Andrew
                                              >
                                              >
                                              > ------------------------------------
                                              >
                                              > Yahoo! Groups Links
                                              >
                                              >
                                              >

                                              --------------------------------------
                                              Jan Algermissen

                                              Mail: algermissen@...
                                              Blog: http://algermissen.blogspot.com/
                                              Home: http://www.jalgermissen.com
                                              --------------------------------------
                                            • Jan Algermissen
                                              ... Yes, exactly. When a service uses Atom and chooses some kind of extension, the client is unable to know this before the interaction because it cannot be
                                              Message 22 of 25 , Nov 6, 2009
                                                On Nov 6, 2009, at 10:48 PM, Will Hartung wrote:

                                                > On Fri, Nov 6, 2009 at 1:37 PM, Jan Algermissen <algermissen1971@...
                                                > > wrote:
                                                >> I meant that (ideally and stretching the point) services should make
                                                >> use of
                                                >> as much hypermedia as they can. If they know about foo links and if
                                                >> they can
                                                >> provide a foo link they should do so.
                                                >> So when clients do not find a foo link they can reasonably 'believe'
                                                >> that
                                                >> the server cannot provide one.
                                                >
                                                > Where does the client get this expectation that a "foo" link exists or
                                                > should exist at all?

                                                Yes, exactly. When a service uses Atom and chooses some kind of
                                                extension,
                                                the client is unable to know this before the interaction because it
                                                cannot
                                                be specified. The client can only observe it and then trust the server
                                                to
                                                keep using the extension if it (the client) chosses to implement the
                                                extension.

                                                This calls for things like 'profiles' to provide a way for the server to
                                                communicate that it uses a certain extension (this has come up on the
                                                atom lists a couple of times and there even was a draft once).

                                                OTH, it seems contrary to what REST is aiming at. From a REST POV the
                                                understanding really is (IMHO) that the client makes observations,
                                                probably 'implements' them and then trusts the server to 'do its
                                                best'.

                                                And this is what is fine on the human Web (because we can compensate
                                                should such expectations break) and machine clients can not.

                                                I observe the 1-click at Amazon. I like it. I start using it. When
                                                it's suddenly gone I just go look what is there instead. Maybe use that
                                                old shopping cart again. Programs cannot do this.

                                                The latter is not even a problem because they can just fail and a
                                                human admin can find a solution. But trying to convince busniess people
                                                to base the entire architecture of an enterprise on this model is
                                                an excercise where you risk your credibility as an IT professional :-)



                                                >
                                                > If the client is expecting a "foo" link and a service isn't providing
                                                > one, then, I'd argue that there is a mismatch in the protocol that the
                                                > client is using and the one the server is using (whether by design,
                                                > version incompatibility, or bug, doesn't much matter).

                                                Right. But how to express the protocol? That is really the question.
                                                If you bundle up hypermedia semantics (media types, extensions,
                                                link rels, query params) you usually do not stick them in a single
                                                spec and therefore you do not have a place to define that you
                                                use exactly that bundle.

                                                >
                                                > Simply, when you have this kind of mis-communication, someone is using
                                                > the "wrong" protocol, or isn't following the spec properly of the
                                                > agreed upon/advertised protocol.

                                                See above. Which spec.

                                                >
                                                > The specification will dictate when and where a service will provide
                                                > the "foo" link, and where the client can expect to find one.
                                                >

                                                See above.

                                                Jan


                                                >
                                                > Regards,
                                                >
                                                > Will Hartung
                                                > (willh@...)

                                                --------------------------------------
                                                Jan Algermissen

                                                Mail: algermissen@...
                                                Blog: http://algermissen.blogspot.com/
                                                Home: http://www.jalgermissen.com
                                                --------------------------------------
                                              • Will Hartung
                                                ... When talking machine to machine, I don t think a REST client is any different in terms of rigidity than any other remote protocol. The REST client will do
                                                Message 23 of 25 , Nov 6, 2009
                                                  On Fri, Nov 6, 2009 at 3:25 PM, Jan Algermissen <algermissen1971@...> wrote:
                                                  > OTH, it seems contrary to what REST is aiming at. From a REST POV the
                                                  > understanding really is (IMHO) that the client makes observations,
                                                  > probably 'implements' them and then trusts the server to 'do its
                                                  > best'.

                                                  When talking machine to machine, I don't think a REST client is any
                                                  different in terms of rigidity than any other remote protocol. The
                                                  REST client will do what it's told with the payloads it sends and
                                                  receives.

                                                  To a human, a robust REST service should be able to be "discovered".
                                                  At this level, REST can be a GUI view to a normal protocols Command
                                                  Line view.

                                                  In theory, with little more than a host name, a human can "crawl" a
                                                  REST service, and discover it features and data types.

                                                  Each payload tells the user what are valid edges on the graph that
                                                  makes up the API. In theory, with robust XSDs, which can be self
                                                  documenting, the user can learn how to build those payloads, and what
                                                  is and is not valid input for them.

                                                  In a GUI, you browse Menus, you look at Dialog options, and slowly,
                                                  over time, you can learn much about the application and it's
                                                  capabilities. REST can be similar. The Common Interface means certain
                                                  aspects of the API simply are left unsaid, the operations defined by
                                                  the Common Interface. Whether a resource supports the Common Interface
                                                  is in itself can be discoverable (for example, using OPTIONS with
                                                  HTTP).

                                                  So, in this case, a REST interface can be like Literal Programming.
                                                  Imagine if each payload were an XML document, with an accompanying
                                                  XSD, and, also, a XSLT processing instruction point to a template that
                                                  renders a complete HTML, human readable description of the payload.

                                                  But, none of this helps machine clients. It help people CREATE machine
                                                  clients, but once created, as we all well know, machine clients are
                                                  bone stupid and aggravatingly literal.

                                                  If a service changes, and thus breaks an existing machine client, a
                                                  user can, in theory, rely on the discoverable nature to fix the client
                                                  and bring it back on line. But obviously if you need to truly rely on
                                                  this transaction, it would be better to work with a guarantee of some
                                                  kind from the provider that the service simply will not change
                                                  underneath the feet of deployed clients (an SLA).

                                                  At an automated level, the focus on the link relationships, rather
                                                  than the URIs themselves, lets the underlying infrastructure change,
                                                  potentially in even dramatic ways, without affect (we've seen how
                                                  services like Amazon and Ebay have grown with us as consumers being
                                                  pretty much none the wiser of the physical deployment aspects). By
                                                  using a backwards compatible formats, older clients keep working,
                                                  newer clients get new functionality.

                                                  The machine web can handle physical changes fairly easily, with a
                                                  robust client, and cooperative back ends. As long as the initial entry
                                                  points are properly supported, most everything else can be discovered
                                                  by the client as it does it's processing.

                                                  However, the machine web can not handle incompatible API changes on
                                                  its own. It simply can't. The clients are too rigid, as they must be.

                                                  Earlier someone mentioned how Firefox doesn't have to be rewritten to
                                                  use Google, or Amazon, or Ebay. In terms of RENDERING the servers
                                                  content, they're correct. The fundamental difference is that Firefox
                                                  is not USING those services. The Human user is. The human is
                                                  interpreting the resource representations and leveraging that
                                                  information to perform their task (search, buying, bidding, whatever).

                                                  The contract between Firefox and Google is the same "I send you URLs,
                                                  you send me HTML". The HTML is "opaque" to Firefox. It simply does not
                                                  care what is being returned. It's job is not to care, rather it's job
                                                  is to execute the payload, and present the results to the user.

                                                  Now, if Firefox asked Google for "index.html", and Google replied
                                                  "Here you go, text/html" and then streamed JPEG content, Firefox would
                                                  blink, pause, go WTF, and finally dump a load of gibberish for the
                                                  Human to interpret, since the JPEG content is most certainly NOT HTML
                                                  like was asked for and promised.

                                                  The machine web is cold, uncaring, and not very tolerant of change.
                                                  It's particularly stubborn when it's lied too.

                                                  I don't think it is appropriate to apply the Human Web to the Machine
                                                  Web in this sense. REST is no magic bullet, REST offers no
                                                  "intuition", or "interpretation" to make the machine web less rigid or
                                                  more forgiving. A Client can be, modern web browsers can do amazing
                                                  guess work and work almost at a "do what I mean" level. But they leave
                                                  much of the hard part of leveraging actual services to the Carbon
                                                  Based Lifeform driving the keyboard.

                                                  Regards,

                                                  Will Hartung
                                                  (willh@...)
                                                • Andrew Wahbe
                                                  ... Yes this terminology is something worth getting consensus on. I was using the terms client and underlying platform for your user agent and client
                                                  Message 24 of 25 , Nov 6, 2009
                                                    On Fri, Nov 6, 2009 at 3:17 PM, Jan Algermissen <algermissen1971@...> wrote:
                                                    >
                                                    > On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:
                                                    >>
                                                    >> Ok so right out of the gate I have issues with this. "Coding a client
                                                    >> for a service" seems unRESTful to me. Firefox is not coded for Google,
                                                    >> Facebook or Amazon. It is coded for URIs, HTTP and HTML (and HTML's
                                                    >> "friends" CSS, Javascript etc.).
                                                    >
                                                    > Ok, yes. I should have made the distinction between the 'user agent' and the
                                                    > program that makes use of it. At least this is my mental model: you have a
                                                    > library that implements all the specs that make sense to implement (meaning:
                                                    > not only the ones for this service) and this piece is equivalent to the
                                                    > browser. Then, you need some piece of code that uses the user agent to
                                                    > interact with the service (or the Web for that matter). This piece of code
                                                    > is equivalent to the human being. Inside this code (or its configuration)
                                                    > one must manifest some expectations (e.g. that the search resource is there
                                                    > so the user agent can carry out the search and hand the result back to the
                                                    > program.

                                                    Yes this terminology is something worth getting consensus on. I was
                                                    using the terms "client" and "underlying platform" for your "user
                                                    agent" and "client program" respectively.

                                                    But I still think there is a client program in the case of a web
                                                    browser -- it is the window manager in the OS. Take the human being
                                                    out of the system for a minute and think about how the web works. Then
                                                    try using that as the model for your own systems.

                                                    >
                                                    > If you want to get rid of that assumption you'd have to come up with a way
                                                    > for the service to actually drive the client program (like a GUI app is
                                                    > driven by the GUI). However, this does not work because the client is a
                                                    > state machine on its own and cannot be entirely driven by the hyper,edia
                                                    > received from the server. At some point there must be 'invocations of goals'
                                                    > by the client side program.
                                                    >
                                                    See my email that elaborates on CCXML. The hypermedia document can be
                                                    seen as a description of a state machine for handling client program
                                                    events that is executed by the user agent. In response to those
                                                    events, messages/events can be sent back down to the client or HTTP
                                                    requests can be placed to the server. Often those requests to the
                                                    server cause a new state machine to be loaded by the user agent. This
                                                    is not only a description of the execution of a CCXML browser, but
                                                    also a VoiceXML browser and an HTML browser. You just have to properly
                                                    define the user agent and the client program to see it that way.

                                                    From this perspective, the user agent is a dynamic mediator between
                                                    the client program's event model and the server's resource model. The
                                                    currently loaded hypermedia document controls the behavior of the
                                                    mediator. So if you are using the right media type, the client's
                                                    "goals" are expressed in terms of the client program's event model and
                                                    translated into actions on the server's resources by the user agent.

                                                    >
                                                    >> Your client will only have code that
                                                    >> has a notion of search invocation if it is inherent in the media type
                                                    >> (including extensions and relations). But that is not necessary for
                                                    >> search to work. The client could be performing a search without
                                                    >> "knowing" it, because a combination of the media type, the current
                                                    >> representation/state, and the client disposition and/or client side
                                                    >> events have caused the search link to be followed. This is what
                                                    >> happens when I use my browser to do a Google search. I don't see why
                                                    >> this can't be the case for media types other than HTML (and it
                                                    >> certainly would be for VoiceXML and CCXML).
                                                    >
                                                    > Yes, great model. But what is driving the whole thing? With the browser it
                                                    > is the human being that drives the interaction because she e.g. wants to buy
                                                    > a book. In the machine world you need a process that initiates a goal and
                                                    > this goal includes assumptions.
                                                    >
                                                    >
                                                    >>
                                                    >>> If the service does not provide the
                                                    >>> search resource anymore the client will break (if you code it to expect
                                                    >>> that
                                                    >>> there is a search resource and sudden;y there is none what else could the
                                                    >>> code do?). Humans can work on a solution for the problem, software cannot
                                                    >>> (unless we go into AI of some form).
                                                    >>
                                                    >> I'm not sure what is "broken" here. The service seems broken, but I'm
                                                    >> not sure if the client is broken -- you should be able to point it at
                                                    >> any other service that supports the client's media type(s) and it
                                                    >> should still work just fine.
                                                    >
                                                    > Yeah - and this is precisely what you cannot utter in a room full with the
                                                    > guys that assign the budget or care about the company being sued. Would you
                                                    > pay for Google's API and then, if part of the service disappears just go of
                                                    > to some other service on the Web?
                                                    >
                                                    This isn't a technical problem is it? The contract you are looking for
                                                    here is a legal one isn't it?

                                                    <snip>
                                                    >
                                                    > Right. But as said above: there are a substantial number of people that
                                                    > won't buy into it. And often rightly so because when you assign budget to
                                                    > something. It is all about documenting the assumptions that might break. I
                                                    > do not see media types to be the means where this can be done. Especialy not
                                                    > when a service uses a combination of hypermedia semantics. Or how would you
                                                    > express that a service pronises to use a certain Atom extension? You could
                                                    > if you'd define application/myatom and make the extension mandatory but this
                                                    > obviously breaks orthogonality.
                                                    >
                                                    <snip>

                                                    So here's an extension of my earlier observation about media types
                                                    being "client specific" standards. This model tends to produce a
                                                    situation where there are orders of magnitude more services than
                                                    clients -- actually, you can argue that it is designed to do that.
                                                    Compare the number of web browsers to the number of web sites.

                                                    Also, think of extensions as the evolution of the media type. A
                                                    specific combination of extensions can be thought of as a version of
                                                    the media type (and the versions might branch quite heavily). A
                                                    version of a client supports a version of the media type.

                                                    If you put these together, you get the contracts that are quite common
                                                    in the web today. e.g. "this service is designed to work with IE 8,
                                                    Firefox 3+ and Safari 4+." Is this ideal? No. But so far the web
                                                    hasn't been very successful at doing much better than this.

                                                    Andrew
                                                  • Jan Algermissen
                                                    ... Picking this up again: Hypermedia specifications[1] implicitly define goals. They do this by establishing semantics on resources[2] and expressing client
                                                    Message 25 of 25 , Nov 9, 2009
                                                      On Nov 6, 2009, at 8:41 PM, Andrew Wahbe wrote:

                                                      > the media type exists
                                                      > outside of the context of your service.

                                                      Picking this up again:

                                                      Hypermedia specifications[1] implicitly define goals. They do this by
                                                      establishing semantics on resources[2] and expressing client goals in
                                                      terms of these semantics. For example, such specifications would
                                                      define that a client can 'place an order' (the goal) by POSTing order
                                                      data to some resource that it discovered from received hypermedia as
                                                      being the order-processor.

                                                      All the available hypermedia specifcations establish the set of goals
                                                      that clients and servers can use during their communication.

                                                      Putting this in the context of service descriptions, I think that
                                                      services must describe what goals they support and that this on the
                                                      one hand provides clients with a means for service discovery and on
                                                      the other hand establishes the contract bteween client and server that
                                                      we've been talking about recently.

                                                      Makes sense?

                                                      Jan



                                                      [1] Media types, link relations, extensions,...
                                                      [2] depending on how they appear in the hypermedia received by the
                                                      client.
                                                      IOW their 'linking context'.
                                                      I tried to explain this here:
                                                      http://algermissen.blogspot.com/2009/09/hypermedia-context.html
                                                    Your message has been successfully submitted and would be delivered to recipients shortly.