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

This is REST

Expand Messages
  • Solomon Duskis
    Are there any multi function, data oriented APIs out there that fully embrace Roy Fielding hypertext constraints -
    Message 1 of 28 , Mar 2, 2009
    View Source
    • 0 Attachment
      Are there any multi function, data oriented APIs out there that fully embrace Roy Fielding hypertext constraints - http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?

      I'm still a bit fuzzy on the last point he makes:

      A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)... Failure here implies that out-of-band information is driving interaction instead of hypertext.

      I have a few ideas, but no concrete examples of driving system-to-system data-oriented "services" through in-band information.  That's level of discoverability that I've only heard about discussed in WS-* systems, but have never seen in practice.  Web sites and other human consumable applications can fulfill this requirement because they have the ultimate "discovery engine" we know of as an implicit part of the "system," namely the human brain (or human mind if you'd like to be philosophical about it).

      The system-to-system interaction that I know about generally require a some level of coupling that make discoverability a much more complex issue.  The techniques with which I am familiar almost seem inadequate to the task.  Roy recently said on rest-discuss:

      A lot of people think of systems as static things. Dead things.  REST is not going to appeal to those people. All of its constraints are designed to keep systems living longer than we are willing or able to anticipate.

      Perhaps I'm simply not familiar with the fitting techniques and technologies to create more life-like systems.  Do you know of any APIs that implements a few features and are used in system-to-system that fully embrace the REST hypertext constraints?  Any insight would be greatly appreciated.

      Thanks,

      Solomon Duskis
    • Stefan Tilkov
      Hi Solomon, Check out http://developer.netflix.com/docs/REST_API_Conventions - IMO, the most RESTful popular API out there. Another good example is
      Message 2 of 28 , Mar 2, 2009
      View Source
      • 0 Attachment
        Hi Solomon,

        Check out http://developer.netflix.com/docs/REST_API_Conventions -
        IMO, the most RESTful popular API out there.

        Another good example is Atom/AtomPub, but I guess you knew about that.

        Stefan
        --
        Stefan Tilkov, http://www.innoq.com/blog/st/

        On 02.03.2009, at 23:09, Solomon Duskis wrote:

        > Are there any multi function, data oriented APIs out there that
        > fully embrace Roy Fielding hypertext constraints - http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
        >
        > I'm still a bit fuzzy on the last point he makes:
        >
        >
        > A REST API should be entered with no prior knowledge beyond the
        > initial URI (bookmark)... Failure here implies that out-of-band
        > information is driving interaction instead of hypertext.
        >
        > I have a few ideas, but no concrete examples of driving system-to-
        > system data-oriented "services" through in-band information. That's
        > level of discoverability that I've only heard about discussed in WS-
        > * systems, but have never seen in practice. Web sites and other
        > human consumable applications can fulfill this requirement because
        > they have the ultimate "discovery engine" we know of as an implicit
        > part of the "system," namely the human brain (or human mind if you'd
        > like to be philosophical about it).
        >
        > The system-to-system interaction that I know about generally require
        > a some level of coupling that make discoverability a much more
        > complex issue. The techniques with which I am familiar almost seem
        > inadequate to the task. Roy recently said on rest-discuss:
        >
        > A lot of people think of systems as static things. Dead things.
        > REST is not going to appeal to those people. All of its constraints
        > are designed to keep systems living longer than we are willing or
        > able to anticipate.
        >
        > Perhaps I'm simply not familiar with the fitting techniques and
        > technologies to create more life-like systems. Do you know of any
        > APIs that implements a few features and are used in system-to-system
        > that fully embrace the REST hypertext constraints? Any insight
        > would be greatly appreciated.
        >
        > Thanks,
        >
        > Solomon Duskis
        >
        >
        > <!-- #ygrp-mkp{ border: 1px solid #d8d8d8; font-family: Arial;
        > margin: 14px 0px; padding: 0px 14px; } #ygrp-mkp hr{ border: 1px
        > solid #d8d8d8; } #ygrp-mkp #hd{ color: #628c2a; font-size: 85%; font-
        > weight: bold; line-height: 122%; margin: 10px 0px; } #ygrp-mkp
        > #ads{ margin-bottom: 10px; } #ygrp-mkp .ad{ padding: 0 0; } #ygrp-
        > mkp .ad a{ color: #0000ff; text-decoration: none; } --> <!-- #ygrp-
        > sponsor #ygrp-lc{ font-family: Arial; } #ygrp-sponsor #ygrp-lc
        > #hd{ margin: 10px 0px; font-weight: bold; font-size: 78%; line-
        > height: 122%; } #ygrp-sponsor #ygrp-lc .ad{ margin-bottom: 10px;
        > padding: 0 0; } --> <!-- #ygrp-mlmsg {font-size:13px; font-family:
        > arial,helvetica,clean,sans-serif;*font-size:small;*font:x-small;}
        > #ygrp-mlmsg table {font-size:inherit;font:100%;} #ygrp-mlmsg select,
        > input, textarea {font:99% arial,helvetica,clean,sans-serif;} #ygrp-
        > mlmsg pre, code {font:115% monospace;*font-size:100%;} #ygrp-mlmsg *
        > {line-height:1.22em;} #ygrp-text{ font-family: Georgia; } #ygrp-
        > text p{ margin: 0 0 1em 0; } dd.last p a { font-family: Verdana;
        > font-weight: bold; } #ygrp-vitnav{ padding-top: 10px; font-family:
        > Verdana; font-size: 77%; margin: 0; } #ygrp-vitnav a{ padding: 0
        > 1px; } #ygrp-mlmsg #logo{ padding-bottom: 10px; } #ygrp-reco
        > { margin-bottom: 20px; padding: 0px; } #ygrp-reco #reco-head { font-
        > weight: bold; color: #ff7900; } #reco-category{ font-size: 77%; }
        > #reco-desc{ font-size: 77%; } #ygrp-vital a{ text-decoration:
        > none; } #ygrp-vital a:hover{ text-decoration: underline; } #ygrp-
        > sponsor #ov ul{ padding: 0 0 0 8px; margin: 0; } #ygrp-sponsor #ov
        > li{ list-style-type: square; padding: 6px 0; font-size: 77%; } #ygrp-
        > sponsor #ov li a{ text-decoration: none; font-size: 130%; } #ygrp-
        > sponsor #nc{ background-color: #eee; margin-bottom: 20px;
        > padding: 0 8px; } #ygrp-sponsor .ad{ padding: 8px 0; } #ygrp-
        > sponsor .ad #hd1{ font-family: Arial; font-weight: bold; color:
        > #628c2a; font-size: 100%; line-height: 122%; } #ygrp-sponsor .ad
        > a{ text-decoration: none; } #ygrp-sponsor .ad a:hover{ text-
        > decoration: underline; } #ygrp-sponsor .ad p{ margin: 0; } o{font-
        > size: 0; } .MsoNormal{ margin: 0 0 0 0; } #ygrp-text tt{ font-size:
        > 120%; } blockquote{margin: 0 0 0 4px;} .replbq{margin:4} dd.last p
        > span { margin-right: 10px; font-family: Verdana; font-weight:
        > bold; } dd.last p span.yshortcuts { margin-right: 0; } div.photo-
        > title a, div.photo-title a:active, div.photo-title a:hover,
        > div.photo-title a:visited { text-decoration: none; } div.file-title
        > a, div.file-title a:active, div.file-title a:hover, div.file-title
        > a:visited { text-decoration: none; } #ygrp-msg p { clear: both;
        > padding: 15px 0 3px 0; overflow: hidden; } #ygrp-msg p span { color:
        > #1E66AE; font-weight: bold; } div#ygrp-mlmsg #ygrp-msg p a
        > span.yshortcuts { font-family: Verdana; font-size: 10px; font-
        > weight: normal; } #ygrp-msg p a { font-family: Verdana; font-size:
        > 10px; } #ygrp-mlmsg a { color: #1E66AE; } div.attach-table div div a
        > { text-decoration: none; } div.attach-table { width: 400px; } -->
      • Craig McClanahan
        ... Subbu Allamaraju recently published an article at InfoQ about describing REST based applications that obey this constraint:
        Message 3 of 28 , Mar 2, 2009
        View Source
        • 0 Attachment
          On Mon, Mar 2, 2009 at 2:09 PM, Solomon Duskis <sduskis@...> wrote:
          > Are there any multi function, data oriented APIs out there that fully
          > embrace Roy Fielding hypertext constraints -
          > http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
          >
          > I'm still a bit fuzzy on the last point he makes:
          >
          > A REST API should be entered with no prior knowledge beyond the initial URI
          > (bookmark)... Failure here implies that out-of-band information is driving
          > interaction instead of hypertext.
          >
          > I have a few ideas, but no concrete examples of driving system-to-system
          > data-oriented "services" through in-band information.  That's level of
          > discoverability that I've only heard about discussed in WS-* systems, but
          > have never seen in practice.  Web sites and other human consumable
          > applications can fulfill this requirement because they have the ultimate
          > "discovery engine" we know of as an implicit part of the "system," namely
          > the human brain (or human mind if you'd like to be philosophical about it).
          >
          > The system-to-system interaction that I know about generally require a some
          > level of coupling that make discoverability a much more complex issue.  The
          > techniques with which I am familiar almost seem inadequate to the task.  Roy
          > recently said on rest-discuss:
          >
          > A lot of people think of systems as static things. Dead things.  REST is not
          > going to appeal to those people. All of its constraints are designed to keep
          > systems living longer than we are willing or able to anticipate.
          >
          > Perhaps I'm simply not familiar with the fitting techniques and technologies
          > to create more life-like systems.  Do you know of any APIs that implements a
          > few features and are used in system-to-system that fully embrace the REST
          > hypertext constraints?  Any insight would be greatly appreciated.

          Subbu Allamaraju recently published an article at InfoQ about
          describing REST based applications that obey this constraint:

          http://www.infoq.com/articles/subbu-allamaraju-rest

          which points out that, if you want to go whole hog in this direction,
          you stop describing the URI structure of your application (like we see
          in most REST API descriptions), and start talking about the "rel"
          (relationship) values that can be used to identify semantically
          interesting hyperlinks that the client might want to follow. His
          examples use a <link> element modeled after the way that Atom and HTML
          define it, which seems to be a popular trend for REST APIs that use
          XML.

          After a day of working with a colleague designing some new REST based
          APIs, I was musing about this while watching one of the video blogs I
          enjoy (Hak5 from revision3.com), where they have occasional stories
          about remotely controlled tanks that can fire nerf missiles on
          command. How to model the control of such a thing with a REST API?

          The basic CRUD type operations map pretty cleanly. Presumably, the
          well-known URI of the service will offer me a link I can use for
          creating a new tank in the first place. And, the representation I get
          back can include a "self" link so I can reference it with a GET
          (retrieve an updated representation), a PUT (update properties), or a
          DELETE (remove this tank from my collection). But how does one model
          actually firing the missile? One idea that seems plausible is to
          include a link element with a "fire" relationship, and document (in
          your API spec) that a POST to this URI will cause the missile to be
          launched.

          <tank>
          <name>My First Tank</name>
          <missile-state>LOADED</missile-state>
          <link rel="self" href="http://tanks-r-us.example.com/tanks/0123"/>
          <!-- POST to this link to prime the spring or whatever
          actually launches the missile -->
          <link rel="ready" href="http://tanks-r-us.example.com/..."
          title="Ready Launcher"/>
          <!-- POST to this link to aim the launcher at the specified
          horizontal and vertical coordinates -->
          <link rel="aim" href="http://tanks-r-us.example/com/..."
          title="Aim Tank"/>
          <!-- POST to this link to fire the missle -->
          <link rel="fire" href="http://tanks-r-us.example.com/..."
          title="Fire Missile"/>
          ...
          </tank>

          Presumably, the "fire" link would only be presented by the server when
          the tank was in a state where this operation makes sense (i.e. a
          "fire" link is included only when the missile is currently LOADED).
          But the server should be prepared to handle the case where a client
          tried to fire the missile after someone else had already fired it,
          because they had retrieved their representation earlier.

          A POST makes the most sense, because firing the missile is definitely
          not idempotent :-). Among other things, it will have side effects
          that change the missile-state of my tank (probably first to FIRING,
          then to EMPTY) which I can monitor by doing polled GETs, or being
          notified by some out-of-band event mechanism. And the usual semantics
          for error responses seem to fit pretty well, too:
          * 202 -- if it takes a non-trivial amount of time to fire the missile,
          the server might accept the request
          and return a URI to monitor for completion
          * 401 -- who the heck are you
          * 403 -- sorry , you're not allowed to fire my missile
          * 409 -- nobody can fire a missile when the launcher is empty (presumably
          someone else beat you to the punch, so your reference to this URI is stale)

          In the particular use case of firing, there isn't much need for a
          request entity (although, if a tank had more than one missile
          launcher, you might model things by including a field in the request
          entity to select which launcher to fire). But, in principle, you
          could include an encapsulation of whatever information is needed for
          the server to do what you want it to do.

          Earlier threads have discussed firing off (possibly transactional)
          business logic. The same sort of approach would work there.

          Craig McClanahan

          >
          > Thanks,
          >
          > Solomon Duskis
          >
        • mike amundsen
          Craig: love the example. other things to model: - selecting available ammo (possibly request available ammo first, etc.) - changing locations (set co-ords,
          Message 4 of 28 , Mar 2, 2009
          View Source
          • 0 Attachment
            Craig:

            love the example.

            other things to model:
            - selecting available ammo (possibly request available ammo first, etc.)
            - changing locations (set co-ords, change gears, directions, etc.)
            - checking fuel, onboarding additional fuel
            - tracking targets
            - dealing w/ incoming rounds (condition of the tank, etc.)

            gets you thinkin', eh?

            mca
            http://amundsen.com/blog/




            On Mon, Mar 2, 2009 at 19:48, Craig McClanahan <craigmcc@...> wrote:
            > - Show quoted text -
            > On Mon, Mar 2, 2009 at 2:09 PM, Solomon Duskis <sduskis@...> wrote:
            >> Are there any multi function, data oriented APIs out there that fully
            >> embrace Roy Fielding hypertext constraints -
            >> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
            >>
            >> I'm still a bit fuzzy on the last point he makes:
            >>
            >> A REST API should be entered with no prior knowledge beyond the initial URI
            >> (bookmark)... Failure here implies that out-of-band information is driving
            >> interaction instead of hypertext.
            >>
            >> I have a few ideas, but no concrete examples of driving system-to-system
            >> data-oriented "services" through in-band information.  That's level of
            >> discoverability that I've only heard about discussed in WS-* systems, but
            >> have never seen in practice.  Web sites and other human consumable
            >> applications can fulfill this requirement because they have the ultimate
            >> "discovery engine" we know of as an implicit part of the "system," namely
            >> the human brain (or human mind if you'd like to be philosophical about it).
            >>
            >> The system-to-system interaction that I know about generally require a some
            >> level of coupling that make discoverability a much more complex issue.  The
            >> techniques with which I am familiar almost seem inadequate to the task.  Roy
            >> recently said on rest-discuss:
            >>
            >> A lot of people think of systems as static things. Dead things.  REST is not
            >> going to appeal to those people. All of its constraints are designed to keep
            >> systems living longer than we are willing or able to anticipate.
            >>
            >> Perhaps I'm simply not familiar with the fitting techniques and technologies
            >> to create more life-like systems.  Do you know of any APIs that implements a
            >> few features and are used in system-to-system that fully embrace the REST
            >> hypertext constraints?  Any insight would be greatly appreciated.
            >
            > Subbu Allamaraju recently published an article at InfoQ about
            > describing REST based applications that obey this constraint:
            >
            >    http://www.infoq.com/articles/subbu-allamaraju-rest
            >
            > which points out that, if you want to go whole hog in this direction,
            > you stop describing the URI structure of your application (like we see
            > in most REST API descriptions), and start talking about the "rel"
            > (relationship) values that can be used to identify semantically
            > interesting hyperlinks that the client might want to follow.  His
            > examples use a <link> element modeled after the way that Atom and HTML
            > define it, which seems to be a popular trend for REST APIs that use
            > XML.
            >
            > After a day of working with a colleague designing some new REST based
            > APIs, I was musing about this while watching one of the video blogs I
            > enjoy (Hak5 from revision3.com), where they have occasional stories
            > about remotely controlled tanks that can fire nerf missiles on
            > command.  How to model the control of such a thing with a REST API?
            >
            > The basic CRUD type operations map pretty cleanly.  Presumably, the
            > well-known URI of the service will offer me a link I can use for
            > creating a new tank in the first place.  And, the representation I get
            > back can include a  "self" link so I can reference it with a GET
            > (retrieve an updated representation), a PUT (update properties), or a
            > DELETE (remove this tank from my collection).  But how does one model
            > actually firing the missile?  One idea that seems plausible is to
            > include a link element with a "fire" relationship, and document (in
            > your API spec) that a POST to this URI will cause the missile to be
            > launched.
            >
            >    <tank>
            >        <name>My First Tank</name>
            >        <missile-state>LOADED</missile-state>
            >        <link rel="self" href="http://tanks-r-us.example.com/tanks/0123"/>
            >        <!-- POST to this link to prime the spring or whatever
            > actually launches the missile -->
            >        <link rel="ready" href="http://tanks-r-us.example.com/..."
            > title="Ready Launcher"/>
            >        <!-- POST to this link to aim the launcher at the specified
            > horizontal and vertical coordinates -->
            >        <link rel="aim" href="http://tanks-r-us.example/com/..."
            > title="Aim Tank"/>
            >        <!-- POST to this link to fire the missle -->
            >        <link rel="fire" href="http://tanks-r-us.example.com/..."
            > title="Fire Missile"/>
            >        ...
            >    </tank>
            >
            > Presumably, the "fire" link would only be presented by the server when
            > the tank was in a state where this operation makes sense (i.e. a
            > "fire" link is included only when the missile is currently LOADED).
            > But the server should be prepared to handle the case where a client
            > tried to fire the missile after someone else had already fired it,
            > because they had retrieved their representation earlier.
            >
            > A POST makes the most sense, because firing the missile is definitely
            > not idempotent :-).  Among other things, it will have side effects
            > that change the missile-state of my tank (probably first to FIRING,
            > then to EMPTY) which I can monitor by doing polled GETs, or being
            > notified by some out-of-band event mechanism.  And the usual semantics
            > for error responses seem to fit pretty well, too:
            > * 202 -- if it takes a non-trivial amount of time to fire the missile,
            > the server might accept the request
            >  and return a URI to monitor for completion
            > * 401 -- who the heck are you
            > * 403 -- sorry , you're not allowed to fire my missile
            > * 409 -- nobody can fire a missile when the launcher is empty (presumably
            >  someone else beat you to the punch, so your reference to this URI is stale)
            >
            > In the particular use case of firing, there isn't much need for a
            > request entity (although, if a tank had more than one missile
            > launcher, you might model things by including a field in the request
            > entity to select which launcher to fire).  But, in principle, you
            > could include an encapsulation of whatever information is needed for
            > the server to do what you want it to do.
            >
            > Earlier threads have discussed firing off (possibly transactional)
            > business logic.  The same sort of approach would work there.
            >
            > Craig McClanahan
            >
            >>
            >> Thanks,
            >>
            >> Solomon Duskis
            >>
            >
            >
            > ------------------------------------
            >
            > Yahoo! Groups Links
            >
            >
            >
            >
          • Robert Koberg
            ... yea -- thinkin that you want to be on the other side with continuous, open communication :) -Rob
            Message 5 of 28 , Mar 2, 2009
            View Source
            • 0 Attachment
              On Mar 2, 2009, at 8:08 PM, mike amundsen wrote:

              > Craig:
              >
              > love the example.
              >
              > other things to model:
              > - selecting available ammo (possibly request available ammo first,
              > etc.)
              > - changing locations (set co-ords, change gears, directions, etc.)
              > - checking fuel, onboarding additional fuel
              > - tracking targets
              > - dealing w/ incoming rounds (condition of the tank, etc.)
              >
              > gets you thinkin', eh?
              >


              yea -- thinkin' that you want to be on the other side with continuous,
              open communication :)

              -Rob


              >
              >
              > mca
              > http://amundsen.com/blog/
              >
              > On Mon, Mar 2, 2009 at 19:48, Craig McClanahan <craigmcc@...>
              > wrote:
              > > - Show quoted text -
              > > On Mon, Mar 2, 2009 at 2:09 PM, Solomon Duskis <sduskis@...>
              > wrote:
              > >> Are there any multi function, data oriented APIs out there that
              > fully
              > >> embrace Roy Fielding hypertext constraints -
              > >> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
              > >>
              > >> I'm still a bit fuzzy on the last point he makes:
              > >>
              > >> A REST API should be entered with no prior knowledge beyond the
              > initial URI
              > >> (bookmark)... Failure here implies that out-of-band information
              > is driving
              > >> interaction instead of hypertext.
              > >>
              > >> I have a few ideas, but no concrete examples of driving system-to-
              > system
              > >> data-oriented "services" through in-band information. That's
              > level of
              > >> discoverability that I've only heard about discussed in WS-*
              > systems, but
              > >> have never seen in practice. Web sites and other human consumable
              > >> applications can fulfill this requirement because they have the
              > ultimate
              > >> "discovery engine" we know of as an implicit part of the
              > "system," namely
              > >> the human brain (or human mind if you'd like to be philosophical
              > about it).
              > >>
              > >> The system-to-system interaction that I know about generally
              > require a some
              > >> level of coupling that make discoverability a much more complex
              > issue. The
              > >> techniques with which I am familiar almost seem inadequate to the
              > task. Roy
              > >> recently said on rest-discuss:
              > >>
              > >> A lot of people think of systems as static things. Dead things.
              > REST is not
              > >> going to appeal to those people. All of its constraints are
              > designed to keep
              > >> systems living longer than we are willing or able to anticipate.
              > >>
              > >> Perhaps I'm simply not familiar with the fitting techniques and
              > technologies
              > >> to create more life-like systems. Do you know of any APIs that
              > implements a
              > >> few features and are used in system-to-system that fully embrace
              > the REST
              > >> hypertext constraints? Any insight would be greatly appreciated.
              > >
              > > Subbu Allamaraju recently published an article at InfoQ about
              > > describing REST based applications that obey this constraint:
              > >
              > > http://www.infoq.com/articles/subbu-allamaraju-rest
              > >
              > > which points out that, if you want to go whole hog in this
              > direction,
              > > you stop describing the URI structure of your application (like we
              > see
              > > in most REST API descriptions), and start talking about the "rel"
              > > (relationship) values that can be used to identify semantically
              > > interesting hyperlinks that the client might want to follow. His
              > > examples use a <link> element modeled after the way that Atom and
              > HTML
              > > define it, which seems to be a popular trend for REST APIs that use
              > > XML.
              > >
              > > After a day of working with a colleague designing some new REST
              > based
              > > APIs, I was musing about this while watching one of the video
              > blogs I
              > > enjoy (Hak5 from revision3.com), where they have occasional stories
              > > about remotely controlled tanks that can fire nerf missiles on
              > > command. How to model the control of such a thing with a REST API?
              > >
              > > The basic CRUD type operations map pretty cleanly. Presumably, the
              > > well-known URI of the service will offer me a link I can use for
              > > creating a new tank in the first place. And, the representation I
              > get
              > > back can include a "self" link so I can reference it with a GET
              > > (retrieve an updated representation), a PUT (update properties),
              > or a
              > > DELETE (remove this tank from my collection). But how does one
              > model
              > > actually firing the missile? One idea that seems plausible is to
              > > include a link element with a "fire" relationship, and document (in
              > > your API spec) that a POST to this URI will cause the missile to be
              > > launched.
              > >
              > > <tank>
              > > <name>My First Tank</name>
              > > <missile-state>LOADED</missile-state>
              > > <link rel="self" href="http://tanks-r-us.example.com/tanks/0123
              > "/>
              > > <!-- POST to this link to prime the spring or whatever
              > > actually launches the missile -->
              > > <link rel="ready" href="http://tanks-r-us.example.com/..."
              > > title="Ready Launcher"/>
              > > <!-- POST to this link to aim the launcher at the specified
              > > horizontal and vertical coordinates -->
              > > <link rel="aim" href="http://tanks-r-us.example/com/..."
              > > title="Aim Tank"/>
              > > <!-- POST to this link to fire the missle -->
              > > <link rel="fire" href="http://tanks-r-us.example.com/..."
              > > title="Fire Missile"/>
              > > ...
              > > </tank>
              > >
              > > Presumably, the "fire" link would only be presented by the server
              > when
              > > the tank was in a state where this operation makes sense (i.e. a
              > > "fire" link is included only when the missile is currently LOADED).
              > > But the server should be prepared to handle the case where a client
              > > tried to fire the missile after someone else had already fired it,
              > > because they had retrieved their representation earlier.
              > >
              > > A POST makes the most sense, because firing the missile is
              > definitely
              > > not idempotent :-). Among other things, it will have side effects
              > > that change the missile-state of my tank (probably first to FIRING,
              > > then to EMPTY) which I can monitor by doing polled GETs, or being
              > > notified by some out-of-band event mechanism. And the usual
              > semantics
              > > for error responses seem to fit pretty well, too:
              > > * 202 -- if it takes a non-trivial amount of time to fire the
              > missile,
              > > the server might accept the request
              > > and return a URI to monitor for completion
              > > * 401 -- who the heck are you
              > > * 403 -- sorry , you're not allowed to fire my missile
              > > * 409 -- nobody can fire a missile when the launcher is empty
              > (presumably
              > > someone else beat you to the punch, so your reference to this URI
              > is stale)
              > >
              > > In the particular use case of firing, there isn't much need for a
              > > request entity (although, if a tank had more than one missile
              > > launcher, you might model things by including a field in the request
              > > entity to select which launcher to fire). But, in principle, you
              > > could include an encapsulation of whatever information is needed for
              > > the server to do what you want it to do.
              > >
              > > Earlier threads have discussed firing off (possibly transactional)
              > > business logic. The same sort of approach would work there.
              > >
              > > Craig McClanahan
              > >
              > >>
              > >> Thanks,
              > >>
              > >> Solomon Duskis
              > >>
              > >
              > >
              > > ------------------------------------
              > >
              > > Yahoo! Groups Links
              > >
              > >
              > >
              > >
              >
              >
            • mike amundsen
              ... LOL! since REST does not require HTTP[1], this same stateless pattern will work over any continuous, open application protocols. mca
              Message 6 of 28 , Mar 2, 2009
              View Source
              • 0 Attachment
                > yea -- thinkin' that you want to be on the other side with continuous, open
                > communication :)
                >
                LOL!

                since REST does not require HTTP[1], this same stateless pattern will
                work over any "continuous, open" application protocols.

                mca
                http://amundsen.com/blog/

                [1] http://tech.groups.yahoo.com/group/rest-discuss/message/8343




                On Mon, Mar 2, 2009 at 20:15, Robert Koberg <rob@...> wrote:
                >
                > On Mar 2, 2009, at 8:08 PM, mike amundsen wrote:
                >
                >> Craig:
                >>
                >> love the example.
                >>
                >> other things to model:
                >> - selecting available ammo (possibly request available ammo first, etc.)
                >> - changing locations (set co-ords, change gears, directions, etc.)
                >> - checking fuel, onboarding additional fuel
                >> - tracking targets
                >> - dealing w/ incoming rounds (condition of the tank, etc.)
                >>
                >> gets you thinkin', eh?
                >>
                >
                >
                > yea -- thinkin' that you want to be on the other side with continuous, open
                > communication :)
                >
                > -Rob
                >
                >
                >> - Show quoted text -
                >>
                >> mca
                >> http://amundsen.com/blog/
                >>
                >> On Mon, Mar 2, 2009 at 19:48, Craig McClanahan <craigmcc@...> wrote:
                >> > - Show quoted text -
                >> > On Mon, Mar 2, 2009 at 2:09 PM, Solomon Duskis <sduskis@...>
                >> > wrote:
                >> >> Are there any multi function, data oriented APIs out there that fully
                >> >> embrace Roy Fielding hypertext constraints -
                >> >> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
                >> >>
                >> >> I'm still a bit fuzzy on the last point he makes:
                >> >>
                >> >> A REST API should be entered with no prior knowledge beyond the initial
                >> >> URI
                >> >> (bookmark)... Failure here implies that out-of-band information is
                >> >> driving
                >> >> interaction instead of hypertext.
                >> >>
                >> >> I have a few ideas, but no concrete examples of driving
                >> >> system-to-system
                >> >> data-oriented "services" through in-band information.  That's level of
                >> >> discoverability that I've only heard about discussed in WS-* systems,
                >> >> but
                >> >> have never seen in practice.  Web sites and other human consumable
                >> >> applications can fulfill this requirement because they have the
                >> >> ultimate
                >> >> "discovery engine" we know of as an implicit part of the "system,"
                >> >> namely
                >> >> the human brain (or human mind if you'd like to be philosophical about
                >> >> it).
                >> >>
                >> >> The system-to-system interaction that I know about generally require a
                >> >> some
                >> >> level of coupling that make discoverability a much more complex issue.
                >> >>  The
                >> >> techniques with which I am familiar almost seem inadequate to the task.
                >> >>  Roy
                >> >> recently said on rest-discuss:
                >> >>
                >> >> A lot of people think of systems as static things. Dead things.  REST
                >> >> is not
                >> >> going to appeal to those people. All of its constraints are designed to
                >> >> keep
                >> >> systems living longer than we are willing or able to anticipate.
                >> >>
                >> >> Perhaps I'm simply not familiar with the fitting techniques and
                >> >> technologies
                >> >> to create more life-like systems.  Do you know of any APIs that
                >> >> implements a
                >> >> few features and are used in system-to-system that fully embrace the
                >> >> REST
                >> >> hypertext constraints?  Any insight would be greatly appreciated.
                >> >
                >> > Subbu Allamaraju recently published an article at InfoQ about
                >> > describing REST based applications that obey this constraint:
                >> >
                >> >    http://www.infoq.com/articles/subbu-allamaraju-rest
                >> >
                >> > which points out that, if you want to go whole hog in this direction,
                >> > you stop describing the URI structure of your application (like we see
                >> > in most REST API descriptions), and start talking about the "rel"
                >> > (relationship) values that can be used to identify semantically
                >> > interesting hyperlinks that the client might want to follow.  His
                >> > examples use a <link> element modeled after the way that Atom and HTML
                >> > define it, which seems to be a popular trend for REST APIs that use
                >> > XML.
                >> >
                >> > After a day of working with a colleague designing some new REST based
                >> > APIs, I was musing about this while watching one of the video blogs I
                >> > enjoy (Hak5 from revision3.com), where they have occasional stories
                >> > about remotely controlled tanks that can fire nerf missiles on
                >> > command.  How to model the control of such a thing with a REST API?
                >> >
                >> > The basic CRUD type operations map pretty cleanly.  Presumably, the
                >> > well-known URI of the service will offer me a link I can use for
                >> > creating a new tank in the first place.  And, the representation I get
                >> > back can include a  "self" link so I can reference it with a GET
                >> > (retrieve an updated representation), a PUT (update properties), or a
                >> > DELETE (remove this tank from my collection).  But how does one model
                >> > actually firing the missile?  One idea that seems plausible is to
                >> > include a link element with a "fire" relationship, and document (in
                >> > your API spec) that a POST to this URI will cause the missile to be
                >> > launched.
                >> >
                >> >    <tank>
                >> >        <name>My First Tank</name>
                >> >        <missile-state>LOADED</missile-state>
                >> >        <link rel="self"
                >> > href="http://tanks-r-us.example.com/tanks/0123"/>
                >> >        <!-- POST to this link to prime the spring or whatever
                >> > actually launches the missile -->
                >> >        <link rel="ready" href="http://tanks-r-us.example.com/..."
                >> > title="Ready Launcher"/>
                >> >        <!-- POST to this link to aim the launcher at the specified
                >> > horizontal and vertical coordinates -->
                >> >        <link rel="aim" href="http://tanks-r-us.example/com/..."
                >> > title="Aim Tank"/>
                >> >        <!-- POST to this link to fire the missle -->
                >> >        <link rel="fire" href="http://tanks-r-us.example.com/..."
                >> > title="Fire Missile"/>
                >> >        ...
                >> >    </tank>
                >> >
                >> > Presumably, the "fire" link would only be presented by the server when
                >> > the tank was in a state where this operation makes sense (i.e. a
                >> > "fire" link is included only when the missile is currently LOADED).
                >> > But the server should be prepared to handle the case where a client
                >> > tried to fire the missile after someone else had already fired it,
                >> > because they had retrieved their representation earlier.
                >> >
                >> > A POST makes the most sense, because firing the missile is definitely
                >> > not idempotent :-).  Among other things, it will have side effects
                >> > that change the missile-state of my tank (probably first to FIRING,
                >> > then to EMPTY) which I can monitor by doing polled GETs, or being
                >> > notified by some out-of-band event mechanism.  And the usual semantics
                >> > for error responses seem to fit pretty well, too:
                >> > * 202 -- if it takes a non-trivial amount of time to fire the missile,
                >> > the server might accept the request
                >> >  and return a URI to monitor for completion
                >> > * 401 -- who the heck are you
                >> > * 403 -- sorry , you're not allowed to fire my missile
                >> > * 409 -- nobody can fire a missile when the launcher is empty
                >> > (presumably
                >> >  someone else beat you to the punch, so your reference to this URI is
                >> > stale)
                >> >
                >> > In the particular use case of firing, there isn't much need for a
                >> > request entity (although, if a tank had more than one missile
                >> > launcher, you might model things by including a field in the request
                >> > entity to select which launcher to fire).  But, in principle, you
                >> > could include an encapsulation of whatever information is needed for
                >> > the server to do what you want it to do.
                >> >
                >> > Earlier threads have discussed firing off (possibly transactional)
                >> > business logic.  The same sort of approach would work there.
                >> >
                >> > Craig McClanahan
                >> >
                >> >>
                >> >> Thanks,
                >> >>
                >> >> Solomon Duskis
                >> >>
                >> >
                >> >
                >> > ------------------------------------
                >> >
                >> > Yahoo! Groups Links
                >> >
                >> >
                >> >
                >> >
                >>
                >>
                >
                >
              • Craig McClanahan
                ... Or, if things go poorly, there s always the Star Trek solution: Just hope the network doesn t go down
                Message 7 of 28 , Mar 2, 2009
                View Source
                • 0 Attachment
                  On Mon, Mar 2, 2009 at 5:15 PM, Robert Koberg <rob@...> wrote:
                  >
                  > On Mar 2, 2009, at 8:08 PM, mike amundsen wrote:
                  >
                  >> Craig:
                  >>
                  >> love the example.
                  >>
                  >> other things to model:
                  >> - selecting available ammo (possibly request available ammo first,
                  >> etc.)
                  >> - changing locations (set co-ords, change gears, directions, etc.)
                  >> - checking fuel, onboarding additional fuel
                  >> - tracking targets
                  >> - dealing w/ incoming rounds (condition of the tank, etc.)
                  >>
                  >> gets you thinkin', eh?
                  >>
                  >
                  >
                  > yea -- thinkin' that you want to be on the other side with continuous,
                  > open communication :)
                  >
                  > -Rob

                  Or, if things go poorly, there's always the Star Trek solution:

                  <link rel="start-self-destruct-sequence" href="..."/>

                  Just hope the network doesn't go down first if you want to turn it off :-).

                  Craig


                  >
                  >
                  >>
                  >>
                  >> mca
                  >> http://amundsen.com/blog/
                  >>
                  >> On Mon, Mar 2, 2009 at 19:48, Craig McClanahan <craigmcc@...>
                  >> wrote:
                  >> > - Show quoted text -
                  > - Show quoted text -
                  >> > On Mon, Mar 2, 2009 at 2:09 PM, Solomon Duskis <sduskis@...>
                  >> wrote:
                  >> >> Are there any multi function, data oriented APIs out there that
                  >> fully
                  >> >> embrace Roy Fielding hypertext constraints -
                  >> >> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
                  >> >>
                  >> >> I'm still a bit fuzzy on the last point he makes:
                  >> >>
                  >> >> A REST API should be entered with no prior knowledge beyond the
                  >> initial URI
                  >> >> (bookmark)... Failure here implies that out-of-band information
                  >> is driving
                  >> >> interaction instead of hypertext.
                  >> >>
                  >> >> I have a few ideas, but no concrete examples of driving system-to-
                  >> system
                  >> >> data-oriented "services" through in-band information.  That's
                  >> level of
                  >> >> discoverability that I've only heard about discussed in WS-*
                  >> systems, but
                  >> >> have never seen in practice.  Web sites and other human consumable
                  >> >> applications can fulfill this requirement because they have the
                  >> ultimate
                  >> >> "discovery engine" we know of as an implicit part of the
                  >> "system," namely
                  >> >> the human brain (or human mind if you'd like to be philosophical
                  >> about it).
                  >> >>
                  >> >> The system-to-system interaction that I know about generally
                  >> require a some
                  >> >> level of coupling that make discoverability a much more complex
                  >> issue.  The
                  >> >> techniques with which I am familiar almost seem inadequate to the
                  >> task.  Roy
                  >> >> recently said on rest-discuss:
                  >> >>
                  >> >> A lot of people think of systems as static things. Dead things.
                  >> REST is not
                  >> >> going to appeal to those people. All of its constraints are
                  >> designed to keep
                  >> >> systems living longer than we are willing or able to anticipate.
                  >> >>
                  >> >> Perhaps I'm simply not familiar with the fitting techniques and
                  >> technologies
                  >> >> to create more life-like systems.  Do you know of any APIs that
                  >> implements a
                  >> >> few features and are used in system-to-system that fully embrace
                  >> the REST
                  >> >> hypertext constraints?  Any insight would be greatly appreciated.
                  >> >
                  >> > Subbu Allamaraju recently published an article at InfoQ about
                  >> > describing REST based applications that obey this constraint:
                  >> >
                  >> >    http://www.infoq.com/articles/subbu-allamaraju-rest
                  >> >
                  >> > which points out that, if you want to go whole hog in this
                  >> direction,
                  >> > you stop describing the URI structure of your application (like we
                  >> see
                  >> > in most REST API descriptions), and start talking about the "rel"
                  >> > (relationship) values that can be used to identify semantically
                  >> > interesting hyperlinks that the client might want to follow.  His
                  >> > examples use a <link> element modeled after the way that Atom and
                  >> HTML
                  >> > define it, which seems to be a popular trend for REST APIs that use
                  >> > XML.
                  >> >
                  >> > After a day of working with a colleague designing some new REST
                  >> based
                  >> > APIs, I was musing about this while watching one of the video
                  >> blogs I
                  >> > enjoy (Hak5 from revision3.com), where they have occasional stories
                  >> > about remotely controlled tanks that can fire nerf missiles on
                  >> > command.  How to model the control of such a thing with a REST API?
                  >> >
                  >> > The basic CRUD type operations map pretty cleanly.  Presumably, the
                  >> > well-known URI of the service will offer me a link I can use for
                  >> > creating a new tank in the first place.  And, the representation I
                  >> get
                  >> > back can include a  "self" link so I can reference it with a GET
                  >> > (retrieve an updated representation), a PUT (update properties),
                  >> or a
                  >> > DELETE (remove this tank from my collection).  But how does one
                  >> model
                  >> > actually firing the missile?  One idea that seems plausible is to
                  >> > include a link element with a "fire" relationship, and document (in
                  >> > your API spec) that a POST to this URI will cause the missile to be
                  >> > launched.
                  >> >
                  >> >    <tank>
                  >> >        <name>My First Tank</name>
                  >> >        <missile-state>LOADED</missile-state>
                  >> >        <link rel="self" href="http://tanks-r-us.example.com/tanks/0123
                  >> "/>
                  >> >        <!-- POST to this link to prime the spring or whatever
                  >> > actually launches the missile -->
                  >> >        <link rel="ready" href="http://tanks-r-us.example.com/..."
                  >> > title="Ready Launcher"/>
                  >> >        <!-- POST to this link to aim the launcher at the specified
                  >> > horizontal and vertical coordinates -->
                  >> >        <link rel="aim" href="http://tanks-r-us.example/com/..."
                  >> > title="Aim Tank"/>
                  >> >        <!-- POST to this link to fire the missle -->
                  >> >        <link rel="fire" href="http://tanks-r-us.example.com/..."
                  >> > title="Fire Missile"/>
                  >> >        ...
                  >> >    </tank>
                  >> >
                  >> > Presumably, the "fire" link would only be presented by the server
                  >> when
                  >> > the tank was in a state where this operation makes sense (i.e. a
                  >> > "fire" link is included only when the missile is currently LOADED).
                  >> > But the server should be prepared to handle the case where a client
                  >> > tried to fire the missile after someone else had already fired it,
                  >> > because they had retrieved their representation earlier.
                  >> >
                  >> > A POST makes the most sense, because firing the missile is
                  >> definitely
                  >> > not idempotent :-).  Among other things, it will have side effects
                  >> > that change the missile-state of my tank (probably first to FIRING,
                  >> > then to EMPTY) which I can monitor by doing polled GETs, or being
                  >> > notified by some out-of-band event mechanism.  And the usual
                  >> semantics
                  >> > for error responses seem to fit pretty well, too:
                  >> > * 202 -- if it takes a non-trivial amount of time to fire the
                  >> missile,
                  >> > the server might accept the request
                  >> >  and return a URI to monitor for completion
                  >> > * 401 -- who the heck are you
                  >> > * 403 -- sorry , you're not allowed to fire my missile
                  >> > * 409 -- nobody can fire a missile when the launcher is empty
                  >> (presumably
                  >> >  someone else beat you to the punch, so your reference to this URI
                  >> is stale)
                  >> >
                  >> > In the particular use case of firing, there isn't much need for a
                  >> > request entity (although, if a tank had more than one missile
                  >> > launcher, you might model things by including a field in the request
                  >> > entity to select which launcher to fire).  But, in principle, you
                  >> > could include an encapsulation of whatever information is needed for
                  >> > the server to do what you want it to do.
                  >> >
                  >> > Earlier threads have discussed firing off (possibly transactional)
                  >> > business logic.  The same sort of approach would work there.
                  >> >
                  >> > Craig McClanahan
                  >> >
                  >> >>
                  >> >> Thanks,
                  >> >>
                  >> >> Solomon Duskis
                  >> >>
                  >> >
                  >> >
                  >> > ------------------------------------
                  >> >
                  >> > Yahoo! Groups Links
                  > - Show quoted text -
                  >> >
                  >> >
                  >> >
                  >> >
                  >>
                  >>
                  >
                  >
                  >
                  > ------------------------------------
                  >
                  > Yahoo! Groups Links
                  >
                  >
                  >
                  >
                • Solomon Duskis
                  Sorry Stefan, I did mean to reply all :) Perhaps the Netflix API would be considered RESTful, but should we be able to discover ALL of the links like Roy
                  Message 8 of 28 , Mar 3, 2009
                  View Source
                  • 0 Attachment
                    Sorry Stefan, I did mean to reply all :)

                    Perhaps the Netflix API would be considered RESTful, but should we be able to discover ALL of the links like Roy Fielding suggests?   He did say straight out that "there can be only one" when it comes to bookmarks.  Is he putting forth an impossible constraint on data-driven APIs with that rule, or is there more that can be done to implement that constraint?

                    Craig and Subbu's use of "rel" seems like a good start and I think that building on that idea can lead to a "there can be only one" compliant RESTful application.  I think it may be a problem that may be solved with an "As Simple As Possible," well known media-type plus a guide on how to develop "rel" dictionaries.

                    I do want to develop this idea a bit further and get your collective take on the subject, but I think I'll start another thread.  Continuing on this thread seems like a risky proposition given the emphasis on the definition of tank behavior.

                    -Solomon

                    On Tue, Mar 3, 2009 at 2:01 AM, Stefan Tilkov <stefan.tilkov@...> wrote:
                    On 02.03.2009, at 23:40, Solomon Duskis wrote:

                    The Netflix seems like a great starting piont, but isn't "out-of-band information" driving the interaction?  Don't you have to "bookmark" quite a few URLs in order to use the API?  The out of bounds information lives at http://developer.netflix.com/docs/REST_API_Conventions


                    I don't think so; most of the URIs are discovered via <link> elements.

                    Stefan

                    P.S. Did you intentionally reply to me only instead of to the list? 


                    -Solomon

                    On Mon, Mar 2, 2009 at 5:19 PM, Stefan Tilkov <stefan.tilkov@...> wrote:
                    Hi Solomon,

                    Check out http://developer.netflix.com/docs/REST_API_Conventions -
                    IMO, the most RESTful popular API out there.

                    Another good example is Atom/AtomPub, but I guess you knew about that.

                    Stefan
                    --
                    Stefan Tilkov, http://www.innoq.com/blog/st/

                    On 02.03.2009, at 23:09, Solomon Duskis wrote:

                    > Are there any multi function, data oriented APIs out there that
                    > fully embrace Roy Fielding hypertext constraints - http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven?
                    >
                    > I'm still a bit fuzzy on the last point he makes:
                    >
                    >
                    > A REST API should be entered with no prior knowledge beyond the
                    > initial URI (bookmark)... Failure here implies that out-of-band
                    > information is driving interaction instead of hypertext.
                    >
                    > I have a few ideas, but no concrete examples of driving system-to-
                    > system data-oriented "services" through in-band information.  That's
                    > level of discoverability that I've only heard about discussed in WS-
                    > * systems, but have never seen in practice.  Web sites and other
                    > human consumable applications can fulfill this requirement because
                    > they have the ultimate "discovery engine" we know of as an implicit
                    > part of the "system," namely the human brain (or human mind if you'd
                    > like to be philosophical about it).
                    >
                    > The system-to-system interaction that I know about generally require
                    > a some level of coupling that make discoverability a much more
                    > complex issue.  The techniques with which I am familiar almost seem
                    > inadequate to the task.  Roy recently said on rest-discuss:
                    >
                    > A lot of people think of systems as static things. Dead things.
                    > REST is not going to appeal to those people. All of its constraints
                    > are designed to keep systems living longer than we are willing or
                    > able to anticipate.
                    >
                    > Perhaps I'm simply not familiar with the fitting techniques and
                    > technologies to create more life-like systems.  Do you know of any
                    > APIs that implements a few features and are used in system-to-system
                    > that fully embrace the REST hypertext constraints?  Any insight
                    > would be greatly appreciated.
                    >
                    > Thanks,
                    >
                    > Solomon Duskis
                    >
                    >
                    > <!-- #ygrp-mkp{ border: 1px solid #d8d8d8; font-family: Arial;
                    > margin: 14px 0px; padding: 0px 14px; } #ygrp-mkp hr{ border: 1px
                    > solid #d8d8d8; } #ygrp-mkp #hd{ color: #628c2a; font-size: 85%; font-
                    > weight: bold; line-height: 122%; margin: 10px 0px; } #ygrp-mkp
                    > #ads{ margin-bottom: 10px; } #ygrp-mkp .ad{ padding: 0 0; } #ygrp-
                    > mkp .ad a{ color: #0000ff; text-decoration: none; } --> <!-- #ygrp-
                    > sponsor #ygrp-lc{ font-family: Arial; } #ygrp-sponsor #ygrp-lc
                    > #hd{ margin: 10px 0px; font-weight: bold; font-size: 78%; line-
                    > height: 122%; } #ygrp-sponsor #ygrp-lc .ad{ margin-bottom: 10px;
                    > padding: 0 0; } --> <!-- #ygrp-mlmsg {font-size:13px; font-family:
                    > arial,helvetica,clean,sans-serif;*font-size:small;*font:x-small;}
                    > #ygrp-mlmsg table {font-size:inherit;font:100%;} #ygrp-mlmsg select,
                    > input, textarea {font:99% arial,helvetica,clean,sans-serif;} #ygrp-
                    > mlmsg pre, code {font:115% monospace;*font-size:100%;} #ygrp-mlmsg *
                    > {line-height:1.22em;} #ygrp-text{ font-family: Georgia;        } #ygrp-
                    > text p{ margin: 0 0 1em 0; } dd.last p a { font-family: Verdana;
                    > font-weight: bold; } #ygrp-vitnav{ padding-top: 10px; font-family:
                    > Verdana; font-size: 77%; margin: 0; } #ygrp-vitnav a{ padding: 0
                    > 1px; } #ygrp-mlmsg #logo{ padding-bottom: 10px; } #ygrp-reco
                    > { margin-bottom: 20px; padding: 0px; } #ygrp-reco #reco-head { font-
                    > weight: bold; color: #ff7900; } #reco-category{ font-size: 77%; }
                    > #reco-desc{ font-size: 77%; } #ygrp-vital a{ text-decoration:
                    > none; } #ygrp-vital a:hover{ text-decoration: underline; } #ygrp-
                    > sponsor #ov ul{ padding: 0 0 0 8px; margin: 0; } #ygrp-sponsor #ov
                    > li{ list-style-type: square; padding: 6px 0; font-size: 77%; } #ygrp-
                    > sponsor #ov li a{ text-decoration: none; font-size: 130%; } #ygrp-
                    > sponsor #nc{ background-color: #eee;    margin-bottom: 20px;
                    > padding: 0 8px; } #ygrp-sponsor .ad{ padding: 8px 0; } #ygrp-
                    > sponsor .ad #hd1{ font-family: Arial; font-weight: bold; color:
                    > #628c2a; font-size: 100%; line-height: 122%; } #ygrp-sponsor .ad
                    > a{ text-decoration: none; } #ygrp-sponsor .ad a:hover{ text-
                    > decoration: underline; } #ygrp-sponsor .ad p{ margin: 0; } o{font-
                    > size: 0; } .MsoNormal{ margin: 0 0 0 0; } #ygrp-text tt{ font-size:
                    > 120%; } blockquote{margin: 0 0 0 4px;} .replbq{margin:4} dd.last p
                    > span { margin-right: 10px; font-family: Verdana; font-weight:
                    > bold; } dd.last p span.yshortcuts { margin-right: 0; } div.photo-
                    > title a, div.photo-title a:active, div.photo-title a:hover,
                    > div.photo-title a:visited { text-decoration: none; } div.file-title
                    > a, div.file-title a:active, div.file-title a:hover, div.file-title
                    > a:visited { text-decoration: none; } #ygrp-msg p { clear: both;
                    > padding: 15px 0 3px 0; overflow: hidden; } #ygrp-msg p span { color:
                    > #1E66AE; font-weight: bold; } div#ygrp-mlmsg #ygrp-msg p a
                    > span.yshortcuts { font-family: Verdana; font-size: 10px; font-
                    > weight: normal; } #ygrp-msg p a { font-family: Verdana; font-size:
                    > 10px; } #ygrp-mlmsg a { color: #1E66AE; } div.attach-table div div a
                    > { text-decoration: none; } div.attach-table { width: 400px; } -->



                    ------------------------------------

                    Yahoo! Groups Links

                    <*> To visit your group on the web, go to:
                       http://groups.yahoo.com/group/rest-discuss/

                    <*> Your email settings:
                       Individual Email | Traditional

                    <*> To change settings online go to:
                       http://groups.yahoo.com/group/rest-discuss/join
                       (Yahoo! ID required)

                    <*> To change settings via email:
                       mailto:rest-discuss-digest@yahoogroups.com
                       mailto:rest-discuss-fullfeatured@yahoogroups.com

                    <*> To unsubscribe from this group, send an email to:
                       rest-discuss-unsubscribe@yahoogroups.com

                    <*> Your use of Yahoo! Groups is subject to:
                       http://docs.yahoo.com/info/terms/




                  • Simon Reinhardt
                    ... This is basically what RDF provides: a common data model (and a bunch of defined formats for it) and a simple, distributed way for defining your rel
                    Message 9 of 28 , Mar 3, 2009
                    View Source
                    • 0 Attachment
                      Solomon Duskis wrote:
                      > Craig and Subbu's use of "rel" seems like a good start and I think that
                      > building on that idea can lead to a "there can be only one" compliant
                      > RESTful application. I think it may be a problem that may be solved
                      > with an "As Simple As Possible," well known media-type plus a guide on
                      > how to develop "rel" dictionaries.

                      This is basically what RDF provides: a common data model (and a bunch of defined formats for it) and a simple, distributed way for defining your "rel" values, encouraging you to re-use the ones defined by others so that a Web service client needs less built-in knowledge about your service.
                      And Linked Data [1] is all about taking one entry point and traversing the data Web from there dynamically by following the links provided (choosing those which have a "rel" type that matches your intentions). Linked Data is mainly about linking up open data of course but its principles can easily be applied to closed applications which, I think, would benefit from that.
                      Just one way of doing it, but I more and more think that the ideas behind Linked Data and REST overlap largely. :-)

                      Regards,
                      Simon

                      [1] http://linkeddata.org/
                    • Solomon Duskis
                      I was afraid someone was going to bring up RDF :). Thanks for the advice, though. I ll take a look at linkeddata. -Solomon On Tue, Mar 3, 2009 at 10:58 AM,
                      Message 10 of 28 , Mar 3, 2009
                      View Source
                      • 0 Attachment
                        I was afraid someone was going to bring up RDF :).  Thanks for the advice, though.  I'll take a look at linkeddata.

                        -Solomon

                        On Tue, Mar 3, 2009 at 10:58 AM, Simon Reinhardt <simon.reinhardt@...> wrote:
                        Solomon Duskis wrote:
                        > Craig and Subbu's use of "rel" seems like a good start and I think that
                        > building on that idea can lead to a "there can be only one" compliant
                        > RESTful application.  I think it may be a problem that may be solved
                        > with an "As Simple As Possible," well known media-type plus a guide on
                        > how to develop "rel" dictionaries.

                        This is basically what RDF provides: a common data model (and a bunch of defined formats for it) and a simple, distributed way for defining your "rel" values, encouraging you to re-use the ones defined by others so that a Web service client needs less built-in knowledge about your service.
                        And Linked Data [1] is all about taking one entry point and traversing the data Web from there dynamically by following the links provided (choosing those which have a "rel" type that matches your intentions). Linked Data is mainly about linking up open data of course but its principles can easily be applied to closed applications which, I think, would benefit from that.
                        Just one way of doing it, but I more and more think that the ideas behind Linked Data and REST overlap largely. :-)

                        Regards,
                         Simon

                        [1] http://linkeddata.org/


                        ------------------------------------

                        Yahoo! Groups Links

                        <*> To visit your group on the web, go to:
                           http://groups.yahoo.com/group/rest-discuss/

                        <*> Your email settings:
                           Individual Email | Traditional

                        <*> To change settings online go to:
                           http://groups.yahoo.com/group/rest-discuss/join
                           (Yahoo! ID required)

                        <*> To change settings via email:
                           mailto:rest-discuss-digest@yahoogroups.com
                           mailto:rest-discuss-fullfeatured@yahoogroups.com

                        <*> To unsubscribe from this group, send an email to:
                           rest-discuss-unsubscribe@yahoogroups.com

                        <*> Your use of Yahoo! Groups is subject to:
                           http://docs.yahoo.com/info/terms/


                      • Roy T. Fielding
                        ... I think you misread that. There might be many different entry points to an application, each of which is bookmarkable. The point was that the client only
                        Message 11 of 28 , Mar 3, 2009
                        View Source
                        • 0 Attachment
                          On Mar 3, 2009, at 6:11 AM, Solomon Duskis wrote:
                          > Sorry Stefan, I did mean to reply all :)
                          >
                          > Perhaps the Netflix API would be considered RESTful, but should we
                          > be able to discover ALL of the links like Roy Fielding suggests?
                          > He did say straight out that "there can be only one" when it comes
                          > to bookmarks. Is he putting forth an impossible constraint on data-
                          > driven APIs with that rule, or is there more that can be done to
                          > implement that constraint?
                          >

                          I think you misread that. There might be many different entry points
                          to an application, each of which is bookmarkable. The point was that
                          the client only needs to know one of them, not that there is only
                          one of them to know.

                          ....Roy
                        • Julian Everett
                          The relevance of the REST architectural style to Linked Data and OWL/SKOS/etc has been nagging away in the back of my mind for the last few months. The idea of
                          Message 12 of 28 , Mar 3, 2009
                          View Source
                          • 0 Attachment
                            The relevance of the REST architectural style to Linked Data and
                            OWL/SKOS/etc has been nagging away in the back of my mind for the last
                            few months.

                            The idea of defining (and even considering the maintenance overhead of)
                            an OWL snapshot of a knowledge domain and binding to it via restricted
                            vocabulary metadata fills me with fear. It seems fraught with all the
                            same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                            meaning are continually evolving products of the dynamic social context
                            within which they exist, and that fact surely needs to be addressed in
                            any workable content binding approach...

                            In REST terms, concepts can obviously be modelled as URI-addressable
                            resources and published in different representation formats. For
                            example, the location concept "London, UK" can be modelled as a resource
                            with the address http://dbpedia.org/resource/London and then published
                            in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                            am unsure how the self-describing message and HATEOS constraints
                            translate in this context? The best I can come up with is that the
                            DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                            representation equivalents of standard MIME types (or metamedia types?),
                            and that hypermedia should be used for runtime binding to the immediate
                            sibling nodes of a concept within those standard ontologies (thereby
                            avoiding the versioned contract binding nightmare). Any approach like
                            that would make me feel a lot more comfortable that just tagging stuff
                            with DBpedia URIs, which seems to violate a whole raft of basic
                            architectural principles e.g. encapsulation and separate of
                            interface/implementation.

                            To my (clearly limited) mind, these seem like really important questions
                            and I don't think they are receiving enough consideration in linked
                            data/semantic web circles at present?

                            regards

                            Julian



                            -----Original Message-----
                            From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
                            On Behalf Of Simon Reinhardt
                            Sent: 03 March 2009 15:58
                            Cc: Rest List
                            Subject: Re: [rest-discuss] This is REST

                            Solomon Duskis wrote:
                            > Craig and Subbu's use of "rel" seems like a good start and I think
                            that
                            > building on that idea can lead to a "there can be only one" compliant
                            > RESTful application. I think it may be a problem that may be solved
                            > with an "As Simple As Possible," well known media-type plus a guide on

                            > how to develop "rel" dictionaries.

                            This is basically what RDF provides: a common data model (and a bunch of
                            defined formats for it) and a simple, distributed way for defining your
                            "rel" values, encouraging you to re-use the ones defined by others so
                            that a Web service client needs less built-in knowledge about your
                            service.
                            And Linked Data [1] is all about taking one entry point and traversing
                            the data Web from there dynamically by following the links provided
                            (choosing those which have a "rel" type that matches your intentions).
                            Linked Data is mainly about linking up open data of course but its
                            principles can easily be applied to closed applications which, I think,
                            would benefit from that.
                            Just one way of doing it, but I more and more think that the ideas
                            behind Linked Data and REST overlap largely. :-)

                            Regards,
                            Simon

                            [1] http://linkeddata.org/


                            ------------------------------------

                            Yahoo! Groups Links




                            Please note that the BBC monitors e-mails sent or received. Further communication will signify your consent to this

                            This e-mail has been sent by one of the following wholly-owned subsidiaries of the BBC:

                            BBC Worldwide Limited, Registration Number: 1420028 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                            BBC World News Limited, Registration Number: 04514407 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                            BBC World Distribution Limited, Registration Number: 04514408, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                          • Peter Keane
                            [to the list now...] I agree that these concerns are perhaps not being adequately address in the SemWeb/LinkedData world. Roy F. talks about late binding in
                            Message 13 of 28 , Mar 3, 2009
                            View Source
                            • 0 Attachment
                              [to the list now...]

                              I agree that these concerns are perhaps not being adequately address in the SemWeb/LinkedData world.  Roy F. talks about late binding in 5.2.1.1 "Resources and Resource Identifiers", and I've often thought there was an essential tension there with (some approaches to) the Semantic Web -- almost as if the idea was to skirt around the fact that representations are bound to a resource as late in the process as possible -- this is what makes the "follow your nose" idea of traversing links in hypermedia so important.  It's important that we distinguish resources from representations here -- if the SemWeb describes/trades in resources it'll work out (although that is, I suspect, difficult in practice).  Unfortunately, there is a temptation to equate a URI with a representation -- it dereferences as a representation but *not until* runtime. And making assertions about that representation may be taking "time" out of the equation.  

                              As you say "hypermedia should be used for runtime binding to the immediate sibling nodes of a concept within those standard ontologies" -- seems like an excellent point.  I wonder what implications that might have -- or maybe this is already the approach being taken?

                              --peter keane

                              On Tue, Mar 3, 2009 at 11:53 AM, Julian Everett <julian.everett@...> wrote:

                              The relevance of the REST architectural style to Linked Data and
                              OWL/SKOS/etc has been nagging away in the back of my mind for the last
                              few months.

                              The idea of defining (and even considering the maintenance overhead of)
                              an OWL snapshot of a knowledge domain and binding to it via restricted
                              vocabulary metadata fills me with fear. It seems fraught with all the
                              same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                              meaning are continually evolving products of the dynamic social context
                              within which they exist, and that fact surely needs to be addressed in
                              any workable content binding approach...

                              In REST terms, concepts can obviously be modelled as URI-addressable
                              resources and published in different representation formats. For
                              example, the location concept "London, UK" can be modelled as a resource
                              with the address http://dbpedia.org/resource/London and then published
                              in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                              am unsure how the self-describing message and HATEOS constraints
                              translate in this context? The best I can come up with is that the
                              DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                              representation equivalents of standard MIME types (or metamedia types?),
                              and that hypermedia should be used for runtime binding to the immediate
                              sibling nodes of a concept within those standard ontologies (thereby
                              avoiding the versioned contract binding nightmare). Any approach like
                              that would make me feel a lot more comfortable that just tagging stuff
                              with DBpedia URIs, which seems to violate a whole raft of basic
                              architectural principles e.g. encapsulation and separate of
                              interface/implementation.

                              To my (clearly limited) mind, these seem like really important questions
                              and I don't think they are receiving enough consideration in linked
                              data/semantic web circles at present?

                              regards

                              Julian

                              -----Original Message-----
                              From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
                              On Behalf Of Simon Reinhardt
                              Sent: 03 March 2009 15:58
                              Cc: Rest List
                              Subject: Re: [rest-discuss] This is REST

                              Solomon Duskis wrote:
                              > Craig and Subbu's use of "rel" seems like a good start and I think
                              that
                              > building on that idea can lead to a "there can be only one" compliant
                              > RESTful application. I think it may be a problem that may be solved
                              > with an "As Simple As Possible," well known media-type plus a guide on

                              > how to develop "rel" dictionaries.

                              This is basically what RDF provides: a common data model (and a bunch of
                              defined formats for it) and a simple, distributed way for defining your
                              "rel" values, encouraging you to re-use the ones defined by others so
                              that a Web service client needs less built-in knowledge about your
                              service.
                              And Linked Data [1] is all about taking one entry point and traversing
                              the data Web from there dynamically by following the links provided
                              (choosing those which have a "rel" type that matches your intentions).
                              Linked Data is mainly about linking up open data of course but its
                              principles can easily be applied to closed applications which, I think,
                              would benefit from that.
                              Just one way of doing it, but I more and more think that the ideas
                              behind Linked Data and REST overlap largely. :-)

                              Regards,
                              Simon

                              [1] http://linkeddata.org/

                              ------------------------------------

                              Yahoo! Groups Links

                              Please note that the BBC monitors e-mails sent or received. Further communication will signify your consent to this

                              This e-mail has been sent by one of the following wholly-owned subsidiaries of the BBC:

                              BBC Worldwide Limited, Registration Number: 1420028 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                              BBC World News Limited, Registration Number: 04514407 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                              BBC World Distribution Limited, Registration Number: 04514408, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ


                            • Dong Liu
                              The URI is the thing. The author of a resource knows what exact semantics an identifier intends to refer to. Semantics is always application-specific. The
                              Message 14 of 28 , Mar 3, 2009
                              View Source
                              • 0 Attachment
                                The URI is the thing. The author of a resource knows what exact
                                semantics an identifier intends to refer to. Semantics is always
                                application-specific. The reader should always understand the author
                                in an application. Am I missing something?

                                Cheers,

                                Dong

                                On Tue, Mar 3, 2009 at 1:29 PM, Peter Keane <pkeane@...> wrote:
                                > [to the list now...]
                                >
                                > I agree that these concerns are perhaps not being adequately address in the
                                > SemWeb/LinkedData world.  Roy F. talks about late binding in 5.2.1.1
                                > "Resources and Resource Identifiers", and I've often thought there was an
                                > essential tension there with (some approaches to) the Semantic Web -- almost
                                > as if the idea was to skirt around the fact that representations are bound
                                > to a resource as late in the process as possible -- this is what makes the
                                > "follow your nose" idea of traversing links in hypermedia so important.
                                > It's important that we distinguish resources from representations here -- if
                                > the SemWeb describes/trades in resources it'll work out (although that is, I
                                > suspect, difficult in practice).  Unfortunately, there is a temptation to
                                > equate a URI with a representation -- it dereferences as a representation
                                > but *not until* runtime. And making assertions about that representation may
                                > be taking "time" out of the equation.
                                >
                                > As you say "hypermedia should be used for runtime binding to the immediate
                                > sibling nodes of a concept within those standard ontologies" -- seems like
                                > an excellent point.  I wonder what implications that might have -- or maybe
                                > this is already the approach being taken?
                                >
                                > --peter keane
                                >
                                > On Tue, Mar 3, 2009 at 11:53 AM, Julian Everett <julian.everett@...>
                                > wrote:
                                >>
                                >> The relevance of the REST architectural style to Linked Data and
                                >> OWL/SKOS/etc has been nagging away in the back of my mind for the last
                                >> few months.
                                >>
                                >> The idea of defining (and even considering the maintenance overhead of)
                                >> an OWL snapshot of a knowledge domain and binding to it via restricted
                                >> vocabulary metadata fills me with fear. It seems fraught with all the
                                >> same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                                >> meaning are continually evolving products of the dynamic social context
                                >> within which they exist, and that fact surely needs to be addressed in
                                >> any workable content binding approach...
                                >>
                                >> In REST terms, concepts can obviously be modelled as URI-addressable
                                >> resources and published in different representation formats. For
                                >> example, the location concept "London, UK" can be modelled as a resource
                                >> with the address http://dbpedia.org/resource/London and then published
                                >> in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                                >> am unsure how the self-describing message and HATEOS constraints
                                >> translate in this context? The best I can come up with is that the
                                >> DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                                >> representation equivalents of standard MIME types (or metamedia types?),
                                >> and that hypermedia should be used for runtime binding to the immediate
                                >> sibling nodes of a concept within those standard ontologies (thereby
                                >> avoiding the versioned contract binding nightmare). Any approach like
                                >> that would make me feel a lot more comfortable that just tagging stuff
                                >> with DBpedia URIs, which seems to violate a whole raft of basic
                                >> architectural principles e.g. encapsulation and separate of
                                >> interface/implementation.
                                >>
                                >> To my (clearly limited) mind, these seem like really important questions
                                >> and I don't think they are receiving enough consideration in linked
                                >> data/semantic web circles at present?
                                >>
                                >> regards
                                >>
                                >> Julian
                                >>
                                >> -----Original Message-----
                                >> From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com]
                                >> On Behalf Of Simon Reinhardt
                                >> Sent: 03 March 2009 15:58
                                >> Cc: Rest List
                                >> Subject: Re: [rest-discuss] This is REST
                                >>
                                >> Solomon Duskis wrote:
                                >> > Craig and Subbu's use of "rel" seems like a good start and I think
                                >> that
                                >> > building on that idea can lead to a "there can be only one" compliant
                                >> > RESTful application. I think it may be a problem that may be solved
                                >> > with an "As Simple As Possible," well known media-type plus a guide on
                                >>
                                >> > how to develop "rel" dictionaries.
                                >>
                                >> This is basically what RDF provides: a common data model (and a bunch of
                                >> defined formats for it) and a simple, distributed way for defining your
                                >> "rel" values, encouraging you to re-use the ones defined by others so
                                >> that a Web service client needs less built-in knowledge about your
                                >> service.
                                >> And Linked Data [1] is all about taking one entry point and traversing
                                >> the data Web from there dynamically by following the links provided
                                >> (choosing those which have a "rel" type that matches your intentions).
                                >> Linked Data is mainly about linking up open data of course but its
                                >> principles can easily be applied to closed applications which, I think,
                                >> would benefit from that.
                                >> Just one way of doing it, but I more and more think that the ideas
                                >> behind Linked Data and REST overlap largely. :-)
                                >>
                                >> Regards,
                                >> Simon
                                >>
                                >> [1] http://linkeddata.org/
                                >>
                                >> ------------------------------------
                                >>
                                >> Yahoo! Groups Links
                                >>
                                >> Please note that the BBC monitors e-mails sent or received. Further
                                >> communication will signify your consent to this
                                >>
                                >> This e-mail has been sent by one of the following wholly-owned
                                >> subsidiaries of the BBC:
                                >>
                                >> BBC Worldwide Limited, Registration Number: 1420028 England, Registered
                                >> Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                >> BBC World News Limited, Registration Number: 04514407 England, Registered
                                >> Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                >> BBC World Distribution Limited, Registration Number: 04514408, Registered
                                >> Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                >
                                >
                              • Stuart Charlton
                                Julian, I think I get what the concern is, but I may not be reading you correctly. Are you concerned that a user agent, when interpreting linked data, would
                                Message 15 of 28 , Mar 3, 2009
                                View Source
                                • 0 Attachment

                                  Julian,

                                  I think I get what the concern is, but I may not be reading you correctly.  Are you concerned that a user agent, when interpreting linked data, would be tasked with rigidly conforming to a particular version(s) of OWL ontologies and not have the ability to adapt to evolving meaning?

                                  Or are you trying to find a way to eliminate the need for contract versioning altogether?

                                  If it's the former, there was good paper a few years back that may provide insights to this challenge:

                                  Named Graphs, Provenance and Trust
                                  http://www.www2005.org/cdrom/docs/p613.pdf

                                  Though it doesn't answer everything.  ( I agree there's not enough discussion of the implications of Linked Data and provenance or versioning, or also, how to denote the effects and semantics of updating linked data with POST or PUT).

                                  But the basic jist is this -- ontologies are similar to relational database schemas, and they need to be versioned like data models.  But the benefit is that they're 'open world' and can thus be extended or made equivalent to concepts in other ontologies.    Which extensions or equivalences you want to consume comes down to the level of trust you place on them -- especially if they're consumed dynamically over hypermedia. 

                                  The practice of using named graphs gives you a construct of creating multiple worlds of data that may have different interpretations associated with them, and a language like SPARQL gives you the ability to query across these named graphs with a 'dynamic closed world assumption'.   

                                  I suspect that, practically speaking, any agent is going to have to bind to _some_ version of the ontology that it understood, perhaps dynamically extending it as it goes along (based on hypermedia sensing trusted links), but frankly we're (as an industry) far away from even level of sophistication in our agents  :-)     There are some interesting papers out there on "knowledge programming with sensing" that I think would be quiet inspirational to anyone looking at how a next-generation linked data agent might work.

                                  Cheers
                                  Stu





                                  From: Julian Everett <julian.everett@...>
                                  To: Simon Reinhardt <simon.reinhardt@...>; Rest List <rest-discuss@yahoogroups.com>
                                  Sent: Tuesday, March 3, 2009 9:53:51 AM
                                  Subject: [rest-discuss] Linked Data and REST architectural style (was: This is REST)

                                  The relevance of the REST architectural style to Linked Data and
                                  OWL/SKOS/etc has been nagging away in the back of my mind for the last
                                  few months.

                                  The idea of defining (and even considering the maintenance overhead of)
                                  an OWL snapshot of a knowledge domain and binding to it via restricted
                                  vocabulary metadata fills me with fear. It seems fraught with all the
                                  same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                                  meaning are continually evolving products of the dynamic social context
                                  within which they exist, and that fact surely needs to be addressed in
                                  any workable content binding approach...

                                  In REST terms, concepts can obviously be modelled as URI-addressable
                                  resources and published in different representation formats. For
                                  example, the location concept "London, UK" can be modelled as a resource
                                  with the address http://dbpedia. org/resource/ London and then published
                                  in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                                  am unsure how the self-describing message and HATEOS constraints
                                  translate in this context? The best I can come up with is that the
                                  DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                                  representation equivalents of standard MIME types (or metamedia types?),
                                  and that hypermedia should be used for runtime binding to the immediate
                                  sibling nodes of a concept within those standard ontologies (thereby
                                  avoiding the versioned contract binding nightmare). Any approach like
                                  that would make me feel a lot more comfortable that just tagging stuff
                                  with DBpedia URIs, which seems to violate a whole raft of basic
                                  architectural principles e.g. encapsulation and separate of
                                  interface/implement ation.

                                  To my (clearly limited) mind, these seem like really important questions
                                  and I don't think they are receiving enough consideration in linked
                                  data/semantic web circles at present?

                                  regards

                                  Julian

                                  -----Original Message-----
                                  From: rest-discuss@ yahoogroups. com [mailto:rest-discuss@ yahoogroups. com]
                                  On Behalf Of Simon Reinhardt
                                  Sent: 03 March 2009 15:58
                                  Cc: Rest List
                                  Subject: Re: [rest-discuss] This is REST

                                  Solomon Duskis wrote:

                                  > Craig and Subbu's use of "rel" seems like a good start and I think
                                  that
                                  > building on that idea can lead to a "there can be only one" compliant
                                  > RESTful application. I think it may be a problem that may be solved
                                  > with an "As Simple As Possible," well known media-type plus a guide on

                                  > how to develop "rel" dictionaries.

                                  This is basically what RDF provides: a common data model (and a bunch of
                                  defined formats for it) and a simple, distributed way for defining your
                                  "rel" values, encouraging you to re-use the ones defined by others so
                                  that a Web service client needs less built-in knowledge about your
                                  service.
                                  And Linked Data [1] is all about taking one entry point and traversing
                                  the data Web from there dynamically by following the links provided
                                  (choosing those which have a "rel" type that matches your intentions).
                                  Linked Data is mainly about linking up open data of course but its
                                  principles can easily be applied to closed applications which, I think,
                                  would benefit from that.
                                  Just one way of doing it, but I more and more think that the ideas
                                  behind Linked Data and REST overlap largely. :-)

                                  Regards,
                                  Simon

                                  [1] http://linkeddata. org/

                                  ------------ --------- --------- ------

                                  Yahoo! Groups Links

                                  Please note that the BBC monitors e-mails sent or received. Further communication will signify your consent to this

                                  This e-mail has been sent by one of the following wholly-owned subsidiaries of the BBC:

                                  BBC Worldwide Limited, Registration Number: 1420028 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                  BBC World News Limited, Registration Number: 04514407 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                  BBC World Distribution Limited, Registration Number: 04514408, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ



                                  Be smarter than spam. See how smart SpamGuard is at giving junk email the boot with the All-new Yahoo! Mail
                                • Dong Liu
                                  Does the reality imply that the entry-barrier of semantic web approaches is higher than what industry, or developers, or normal web users can accept? I am
                                  Message 16 of 28 , Mar 3, 2009
                                  View Source
                                  • 0 Attachment
                                    Does the reality imply that the entry-barrier of semantic web
                                    approaches is higher than what industry, or developers, or normal web
                                    users can accept?

                                    I am always scared by the epigram of "So many good ideas are never
                                    heard from again once they embark in a voyage on the semantic gulf. "

                                    Cheers,

                                    Dong

                                    On Tue, Mar 3, 2009 at 3:46 PM, Stuart Charlton
                                    <stuartcharlton@...> wrote:
                                    >
                                    > Julian,
                                    > I think I get what the concern is, but I may not be reading you correctly.
                                    >  Are you concerned that a user agent, when interpreting linked data, would
                                    > be tasked with rigidly conforming to a particular version(s) of OWL
                                    > ontologies and not have the ability to adapt to evolving meaning?
                                    > Or are you trying to find a way to eliminate the need for contract
                                    > versioning altogether?
                                    > If it's the former, there was good paper a few years back that may provide
                                    > insights to this challenge:
                                    > Named Graphs, Provenance and Trust
                                    > http://www.www2005.org/cdrom/docs/p613.pdf
                                    > Though it doesn't answer everything.  ( I agree there's not enough
                                    > discussion of the implications of Linked Data and provenance or versioning,
                                    > or also, how to denote the effects and semantics of updating linked data
                                    > with POST or PUT).
                                    > But the basic jist is this -- ontologies are similar to relational database
                                    > schemas, and they need to be versioned like data models.  But the benefit is
                                    > that they're 'open world' and can thus be extended or made equivalent to
                                    > concepts in other ontologies.    Which extensions or equivalences you want
                                    > to consume comes down to the level of trust you place on them -- especially
                                    > if they're consumed dynamically over hypermedia.
                                    > The practice of using named graphs gives you a construct of creating
                                    > multiple worlds of data that may have different interpretations associated
                                    > with them, and a language like SPARQL gives you the ability to query across
                                    > these named graphs with a 'dynamic closed world assumption'.
                                    > I suspect that, practically speaking, any agent is going to have to bind to
                                    > _some_ version of the ontology that it understood, perhaps dynamically
                                    > extending it as it goes along (based on hypermedia sensing trusted links),
                                    > but frankly we're (as an industry) far away from even level of
                                    > sophistication in our agents  :-)     There are some interesting papers out
                                    > there on "knowledge programming with sensing" that I think would be quiet
                                    > inspirational to anyone looking at how a next-generation linked data agent
                                    > might work.
                                    > Cheers
                                    > Stu
                                    >
                                    >
                                    >
                                    > ________________________________
                                    > From: Julian Everett <julian.everett@...>
                                    > To: Simon Reinhardt <simon.reinhardt@...>; Rest List
                                    > <rest-discuss@yahoogroups.com>
                                    > Sent: Tuesday, March 3, 2009 9:53:51 AM
                                    > Subject: [rest-discuss] Linked Data and REST architectural style (was: This
                                    > is REST)
                                    >
                                    > The relevance of the REST architectural style to Linked Data and
                                    > OWL/SKOS/etc has been nagging away in the back of my mind for the last
                                    > few months.
                                    >
                                    > The idea of defining (and even considering the maintenance overhead of)
                                    > an OWL snapshot of a knowledge domain and binding to it via restricted
                                    > vocabulary metadata fills me with fear. It seems fraught with all the
                                    > same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                                    > meaning are continually evolving products of the dynamic social context
                                    > within which they exist, and that fact surely needs to be addressed in
                                    > any workable content binding approach...
                                    >
                                    > In REST terms, concepts can obviously be modelled as URI-addressable
                                    > resources and published in different representation formats. For
                                    > example, the location concept "London, UK" can be modelled as a resource
                                    > with the address http://dbpedia. org/resource/ London and then published
                                    > in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                                    > am unsure how the self-describing message and HATEOS constraints
                                    > translate in this context? The best I can come up with is that the
                                    > DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                                    > representation equivalents of standard MIME types (or metamedia types?),
                                    > and that hypermedia should be used for runtime binding to the immediate
                                    > sibling nodes of a concept within those standard ontologies (thereby
                                    > avoiding the versioned contract binding nightmare). Any approach like
                                    > that would make me feel a lot more comfortable that just tagging stuff
                                    > with DBpedia URIs, which seems to violate a whole raft of basic
                                    > architectural principles e.g. encapsulation and separate of
                                    > interface/implement ation.
                                    >
                                    > To my (clearly limited) mind, these seem like really important questions
                                    > and I don't think they are receiving enough consideration in linked
                                    > data/semantic web circles at present?
                                    >
                                    > regards
                                    >
                                    > Julian
                                    >
                                    > -----Original Message-----
                                    > From: rest-discuss@ yahoogroups. com [mailto:rest-discuss@ yahoogroups. com]
                                    > On Behalf Of Simon Reinhardt
                                    > Sent: 03 March 2009 15:58
                                    > Cc: Rest List
                                    > Subject: Re: [rest-discuss] This is REST
                                    >
                                    > Solomon Duskis wrote:
                                    >> Craig and Subbu's use of "rel" seems like a good start and I think
                                    > that
                                    >> building on that idea can lead to a "there can be only one" compliant
                                    >> RESTful application. I think it may be a problem that may be solved
                                    >> with an "As Simple As Possible," well known media-type plus a guide on
                                    >
                                    >> how to develop "rel" dictionaries.
                                    >
                                    > This is basically what RDF provides: a common data model (and a bunch of
                                    > defined formats for it) and a simple, distributed way for defining your
                                    > "rel" values, encouraging you to re-use the ones defined by others so
                                    > that a Web service client needs less built-in knowledge about your
                                    > service.
                                    > And Linked Data [1] is all about taking one entry point and traversing
                                    > the data Web from there dynamically by following the links provided
                                    > (choosing those which have a "rel" type that matches your intentions).
                                    > Linked Data is mainly about linking up open data of course but its
                                    > principles can easily be applied to closed applications which, I think,
                                    > would benefit from that.
                                    > Just one way of doing it, but I more and more think that the ideas
                                    > behind Linked Data and REST overlap largely. :-)
                                    >
                                    > Regards,
                                    > Simon
                                    >
                                    > [1] http://linkeddata. org/
                                    >
                                    > ------------ --------- --------- ------
                                    >
                                    > Yahoo! Groups Links
                                    >
                                    > Please note that the BBC monitors e-mails sent or received. Further
                                    > communication will signify your consent to this
                                    >
                                    > This e-mail has been sent by one of the following wholly-owned subsidiaries
                                    > of the BBC:
                                    >
                                    > BBC Worldwide Limited, Registration Number: 1420028 England, Registered
                                    > Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                    > BBC World News Limited, Registration Number: 04514407 England, Registered
                                    > Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                    > BBC World Distribution Limited, Registration Number: 04514408, Registered
                                    > Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                    >
                                    > ________________________________
                                    > Be smarter than spam. See how smart SpamGuard is at giving junk email the
                                    > boot with the All-new Yahoo! Mail
                                    >
                                  • Solomon Duskis
                                    Thank you very much for the clarification. If I understand correctly, the single bookmark constraint means that any initial access to the REST system must
                                    Message 17 of 28 , Mar 4, 2009
                                    View Source
                                    • 0 Attachment
                                      Thank you very much for the clarification. 

                                      If I understand correctly, the single bookmark constraint means that any initial access to the REST system must allow discoverability to every accessible part of the system through some degree of linkage sepration.  There is some path from every point A to point B and back again.  There's some way to discover the entire system using any entry point.

                                      Websites do this all the time.  The homepage can get you just about anywhere on the site through a degree of separation, and everything links back to the homepage.  If you access the website with a bookmark any where on the site and still link to every other available resource with some set of clicks and form entries.

                                      All of the REST APIs that I've seen have:
                                      - resources that are commonly bookmarked but no other resources link back to them. 
                                      - closed subsystems -- resources that interlink but don't link to the rest of the API. 

                                      In other words clients of those REST APIs must use some out of band information, such as human readable API documentation, in order to invoke functionality.  Perhaps it's a problem with the API's media types not interlinking.  However, even if the media types did fully interlink, I simply haven't seen any client-side techniques to perform that discovery of that interlinking in a clean systemic way.

                                      The problem here is either:

                                      A) I don't get it.  I'm missing something fundamental.
                                      B) There's more work to be done here, but it's doable.  This is a great opportunity, similar to what  http://www.infoq.com/articles/subbu-allamaraju-rest discusses
                                      C) Website discover works because there's a human driving the navigation.  REST API discoverability requires a complex "discovery engine" making REST APIs too complex to discover effectively without that engine.  The barrier to entry is too big, 

                                      Given the discussion in the previous thread, it seems like B.  Is my understanding of the theory and practices described here correctest?

                                      -Solomon

                                      On Tue, Mar 3, 2009 at 12:05 PM, Roy T. Fielding <fielding@...> wrote:
                                      On Mar 3, 2009, at 6:11 AM, Solomon Duskis wrote:
                                      Sorry Stefan, I did mean to reply all :)

                                      Perhaps the Netflix API would be considered RESTful, but should we be able to discover ALL of the links like Roy Fielding suggests?   He did say straight out that "there can be only one" when it comes to bookmarks.  Is he putting forth an impossible constraint on data-driven APIs with that rule, or is there more that can be done to implement that constraint?


                                      I think you misread that.  There might be many different entry points
                                      to an application, each of which is bookmarkable.  The point was that
                                      the client only needs to know one of them, not that there is only
                                      one of them to know.

                                      ....Roy


                                    • Julian Everett
                                      Hi Stuart Thanks for the link - that s a very interesting paper. ... Exactly. And I think the ability to adapt to evolving meaning will be dependent on both
                                      Message 18 of 28 , Mar 4, 2009
                                      View Source
                                      • 0 Attachment

                                        Hi Stuart

                                         

                                        Thanks for the link - that’s a very interesting paper.

                                         

                                        > Are you concerned that a user agent,

                                        when interpreting linked data, would be tasked with rigidly conforming to a particular version(s) of OWL ontologies and not have the ability to adapt to evolving meaning?

                                         

                                        Exactly. And I think the ability to adapt to evolving meaning will be dependent on both how the ontology is published and how the client consumes it. Going back to the location example, let’s say I want to start adding structured location metadata to some content which I am publishing online: my motivation for doing so is to leverage the ontology to provide a richer set of related keywords in order to increase site visitors’ content discovery options and drive cross linking. So I start coding..

                                         

                                        Developer Groundhog Day #1

                                        I decide to use GeoNames IDs for the location metadata, and hook a drop-down in my CMS into the GeoNames web service. When a user selects a country or town, I then make a second call back out to GeoNames to pull back the sibling IDs of that node and store both the selected ID and siblings. My content gets published enriched with a list of related GeoNames IDs, and I’m done! Then I discover a problem. Someone really needs a feed of my content, but everything on their site uses GeoRSS format for location. Then someone else asks me a feed but they need the location data expressed as DBpedia resource URIs. I am “helpfully” just about to add new fields to the CMS for GeoRSS and DBpedia IDs and then update all the legacy tagged content, when thankfully someone catches me and forcibly restrains me.

                                         

                                        Developer Groundhog Day #2

                                        So I think “must separate resource from representation, must separate resource from representation” and start coding again. I resolve to identify a true primary key as the internal implementation of my location resource, and settle on long/lat plus a context identifier (e.g. town, village, continent). I add an adapter layer to my web application that translates my internal implementation into a public standard external interface of GeoNames ID, KML, GeoRSS, DBpedia IDs. Ideally I would like the client to be able to specify their desired representation format content-negotiation style, but I’m not sure how that could work practically so opt for a simple configuration option for each client. I’m done! Then I discover a problem. Tibet is liberated; the Basque country declares independence; Croatia, Serbia and Slovenia merge into the United Slovak States; and a whole subset of my inferred location tags are now wrong. I am “helpfully” just about to update all the legacy tagged content, when thankfully someone catches me and forcibly restrains me.

                                         

                                        Developer Groundhog Day #3

                                        I decide I should be late-binding to ontologies at content delivery time rather than early-binding at authoring time. I also realise that I should be storing as little metadata possible: I just need my core internal primary key values. Instead, I add more functionality to my adapter layer and get it to request hypermedia links to sibling nodes in the relevant ontology as well as performing the format translation. In that way my application becomes properly decoupled from ontology versioning issues, and I am always able to publish the current and most relevant set of related links for any piece of content. Happy days.

                                         

                                         

                                        Which maps almost exactly to my experiences of people doing service development:

                                        Developer Groundhog Day #1

                                        Naïve YAGNI: bleed the internals of my domain model into the outside world via auto-generated WSDL/XSDs. Clients are coupled to my implementation details, I can’t change anything and end up in world of pain.

                                        Developer Groundhog Day #2

                                        Contract versioning: abstract domain model behind DTO/adapter layer which is then exposed via versioned WSDL/XSDs. With each new version, system complexity and costs spiral until ultimately no longer viable.

                                        Developer Groundhog Day #3

                                        REST: one codebase, one version, properly decoupled clients. Happy days.

                                         

                                         

                                        Thoughts anyone?

                                         

                                        thanks a lot

                                         

                                        Julian

                                         

                                         

                                        From: Stuart Charlton [mailto:stuartcharlton@...]
                                        Sent: 03 March 2009 21:47
                                        To: Julian Everett; Rest List
                                        Subject: Re: [rest-discuss] Linked Data and REST architectural style (was: This is REST)

                                         

                                         

                                        Julian,

                                         

                                        I think I get what the concern is, but I may not be reading you correctly.  Are you concerned that a user agent, when interpreting linked data, would be tasked with rigidly conforming to a particular version(s) of OWL ontologies and not have the ability to adapt to evolving meaning?

                                         

                                        Or are you trying to find a way to eliminate the need for contract versioning altogether?

                                         

                                        If it's the former, there was good paper a few years back that may provide insights to this challenge:

                                         

                                        Named Graphs, Provenance and Trust

                                        http://www.www2005.org/cdrom/docs/p613.pdf

                                         

                                        Though it doesn't answer everything.  ( I agree there's not enough discussion of the implications of Linked Data and provenance or versioning, or also, how to denote the effects and semantics of updating linked data with POST or PUT).

                                         

                                        But the basic jist is this -- ontologies are similar to relational database schemas, and they need to be versioned like data models.  But the benefit is that they're 'open world' and can thus be extended or made equivalent to concepts in other ontologies.    Which extensions or equivalences you want to consume comes down to the level of trust you place on them -- especially if they're consumed dynamically over hypermedia. 

                                         

                                        The practice of using named graphs gives you a construct of creating multiple worlds of data that may have different interpretations associated with them, and a language like SPARQL gives you the ability to query across these named graphs with a 'dynamic closed world assumption'.   

                                         

                                        I suspect that, practically speaking, any agent is going to have to bind to _some_ version of the ontology that it understood, perhaps dynamically extending it as it goes along (based on hypermedia sensing trusted links), but frankly we're (as an industry) far away from even level of sophistication in our agents  :-)     There are some interesting papers out there on "knowledge programming with sensing" that I think would be quiet inspirational to anyone looking at how a next-generation linked data agent might work.

                                         

                                        Cheers

                                        Stu

                                         

                                         

                                         

                                         


                                        From: Julian Everett <julian.everett@...>
                                        To: Simon Reinhardt <simon.reinhardt@...>; Rest List <rest-discuss@yahoogroups.com>
                                        Sent: Tuesday, March 3, 2009 9:53:51 AM
                                        Subject: [rest-discuss] Linked Data and REST architectural style (was: This is REST)


                                        The relevance of the REST architectural style to Linked Data and
                                        OWL/SKOS/etc has been nagging away in the back of my mind for the last
                                        few months.

                                        The idea of defining (and even considering the maintenance overhead of)
                                        an OWL snapshot of a knowledge domain and binding to it via restricted
                                        vocabulary metadata fills me with fear. It seems fraught with all the
                                        same contract versioning issues as WSDL, DCOM, etc. Knowledge and
                                        meaning are continually evolving products of the dynamic social context
                                        within which they exist, and that fact surely needs to be addressed in
                                        any workable content binding approach...

                                        In REST terms, concepts can obviously be modelled as URI-addressable
                                        resources and published in different representation formats. For
                                        example, the location concept "London, UK" can be modelled as a resource
                                        with the address http://dbpedia. org/resource/ London and then published
                                        in representation formats including RDF, N3, KML, GeoRSS, etc. However I
                                        am unsure how the self-describing message and HATEOS constraints
                                        translate in this context? The best I can come up with is that the
                                        DBpedia, Freebase, OpenCyc ontologies should be viewed as the knowledge
                                        representation equivalents of standard MIME types (or metamedia types?),
                                        and that hypermedia should be used for runtime binding to the immediate
                                        sibling nodes of a concept within those standard ontologies (thereby
                                        avoiding the versioned contract binding nightmare). Any approach like
                                        that would make me feel a lot more comfortable that just tagging stuff
                                        with DBpedia URIs, which seems to violate a whole raft of basic
                                        architectural principles e.g. encapsulation and separate of
                                        interface/implement ation.

                                        To my (clearly limited) mind, these seem like really important questions
                                        and I don't think they are receiving enough consideration in linked
                                        data/semantic web circles at present?

                                        regards

                                        Julian

                                        -----Original Message-----
                                        From: rest-discuss@ yahoogroups. com [mailto:rest-discuss@ yahoogroups. com]
                                        On Behalf Of Simon Reinhardt
                                        Sent: 03 March 2009 15:58
                                        Cc: Rest List
                                        Subject: Re: [rest-discuss] This is REST

                                        Solomon Duskis wrote:

                                        > Craig and Subbu's use of "rel" seems like a good start and I
                                        think
                                        that
                                        > building on that idea can lead to a "there can be only one"
                                        compliant
                                        > RESTful application. I think it may be a problem that may be solved
                                        > with an "As Simple As Possible," well known media-type plus a
                                        guide on

                                        > how to develop "rel" dictionaries.

                                        This is basically what RDF provides: a common data model (and a bunch of
                                        defined formats for it) and a simple, distributed way for defining your
                                        "rel" values, encouraging you to re-use the ones defined by others so
                                        that a Web service client needs less built-in knowledge about your
                                        service.
                                        And Linked Data [1] is all about taking one entry point and traversing
                                        the data Web from there dynamically by following the links provided
                                        (choosing those which have a "rel" type that matches your intentions).
                                        Linked Data is mainly about linking up open data of course but its
                                        principles can easily be applied to closed applications which, I think,
                                        would benefit from that.
                                        Just one way of doing it, but I more and more think that the ideas
                                        behind Linked Data and REST overlap largely. :-)

                                        Regards,
                                        Simon

                                        [1] http://linkeddata. org/

                                        ------------ --------- --------- ------

                                        Yahoo! Groups Links

                                        Please note that the BBC monitors e-mails sent or received. Further communication will signify your consent to this

                                        This e-mail has been sent by one of the following wholly-owned subsidiaries of the BBC:

                                        BBC Worldwide Limited, Registration Number: 1420028 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                        BBC World News Limited, Registration Number: 04514407 England, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ
                                        BBC World Distribution Limited, Registration Number: 04514408, Registered Address: BBC Media Centre, 201 Wood Lane, London, W12 7TQ

                                         


                                        Be smarter than spam. See how smart SpamGuard is at giving junk email the boot with the All-new Yahoo! Mail

                                      • Josh Sled
                                        ... … or: D) People are misusing the term REST in describing their APIs. A good example is some new flickr API I saw last night
                                        Message 19 of 28 , Mar 4, 2009
                                        View Source
                                        • 0 Attachment
                                          Solomon Duskis <sduskis@...> writes:
                                          > All of the REST APIs that I've seen have:
                                          > - resources that are commonly bookmarked but no other resources link back to them. 
                                          > - closed subsystems -- resources that interlink but don't link to the rest of the API. 
                                          >
                                          > In other words clients of those REST APIs must use some out of band information, such as human readable API documentation, in order to invoke functionality.  Perhaps it's a problem with the API's
                                          > media types not interlinking.  However, even if the media types did fully interlink, I simply haven't seen any client-side techniques to perform that discovery of that interlinking in a clean
                                          > systemic way.
                                          >
                                          > The problem here is either:
                                          >
                                          > A) I don't get it.  I'm missing something fundamental.
                                          > B) There's more work to be done here, but it's doable.  This is a great opportunity, similar to what  http://www.infoq.com/articles/subbu-allamaraju-rest discusses
                                          > C) Website discover works because there's a human driving the navigation.  REST API discoverability requires a complex "discovery engine" making REST APIs too complex to discover effectively
                                          > without that engine.  The barrier to entry is too big, 
                                          >
                                          > Given the discussion in the previous thread, it seems like B.  Is my understanding of the theory and practices described here correctest?

                                          … or:
                                          D) People are misusing the term REST in describing their APIs.

                                          A good example is some new flickr API I saw last night
                                          <http://code.flickr.com/blog/2009/03/03/panda-tuesday-the-history-of-the-panda-new-apis-explore-and-you/>,
                                          which uses its own mechanism for cache/polling control, doesn't use
                                          URLs/hypermedia, &c.

                                          I think you're correct in your assessment of the sad state of support
                                          for RESTful APIs. I'd imagine something that used both an out-of-band
                                          description to allow user-agent/clients to build reasonable stubs and
                                          document the potential state space (urls, media-types, which values in
                                          those media types correspond to links, with what semantics, &c.), as
                                          well as navigating the run-time representations to interact with the
                                          service. I don't think I've seen anything strong along those lines.

                                          Though another part of REST is the idea that the media types are widely
                                          and well known, which is at odds with service-specific media types and
                                          service-description documents. People do talk about using Atom/APP and
                                          Microformats/HTML to describe their apps, though. RDF and RDF Forms are
                                          another approach along these lines.

                                          --
                                          ...jsled
                                          http://asynchronous.org/ - a=jsled; b=asynchronous.org; echo ${a}@${b}
                                        • Roy T. Fielding
                                          ... No. This is an application of computers to do something useful, not a math problem or a reachability analysis. Any given client might only be able to
                                          Message 20 of 28 , Mar 4, 2009
                                          View Source
                                          • 0 Attachment
                                            On Mar 4, 2009, at 3:31 AM, Solomon Duskis wrote:
                                            > Thank you very much for the clarification.
                                            >
                                            > If I understand correctly, the single bookmark constraint means
                                            > that any initial access to the REST system must allow
                                            > discoverability to every accessible part of the system through some
                                            > degree of linkage sepration. There is some path from every point A
                                            > to point B and back again. There's some way to discover the entire
                                            > system using any entry point.
                                            >

                                            No. This is an application of computers to do something useful,
                                            not a math problem or a reachability analysis. Any given client
                                            might only be able to reach 1% of a system and still be successful
                                            at doing what they wanted to do. The simplest example of that is
                                            a system using authentication and role-based access control.

                                            In any case, this line of thought is missing the point of REST.
                                            If the application state is entirely defined by the client's
                                            workspace (set of representations) and all possible transitions
                                            away from that state are presented in those representations,
                                            then the potential size of the overall system is irrelevant.
                                            Each state can be considered independently. That is fundamental
                                            to the use of state machines to simplify the understanding of
                                            complex systems.

                                            The client only needs to know what it has in that workspace,
                                            at that time, and so any pre-definition of URI layout or
                                            WSDL-like service semantics is an absolute waste of time as
                                            far as a RESTful architecture is concerned. External artifacts
                                            might help the developers communicate about or improve the design
                                            of their system, just as readable URIs will help a human user
                                            understand where they are in a hypertext user-interface, but
                                            those external artifacts must not have a role in the runtime
                                            architecture if the system is truly hypertext-driven.

                                            ....Roy
                                          • Solomon Duskis
                                            Comments below ... Good question Darrel; it s straight to the point :). I hope that this email will answer that question. I also hope that this will either
                                            Message 21 of 28 , Mar 4, 2009
                                            View Source
                                            • 0 Attachment
                                              Comments below

                                              On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller <darrel.miller@...> wrote:

                                              On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...> wrote:

                                              C) Website discover works because there's a human driving the navigation.  REST API discoverability requires a complex "discovery engine" making REST APIs too complex to discover effectively without that engine.  The barrier to entry is too big, 


                                               
                                              __,_._,_
                                               
                                              I don't understand why you believe it is difficult to get a client application to discover links.  Writing client side code to finding and follow links in an XML or HTML based document is quite trivial.

                                              Darrel
                                               
                                              Good question Darrel; it's straight to the point :).  I hope that this email will answer that question.  I also hope that this will either prove or disprove that I understand what Roy Fielding said in the last email to this group.

                                              Yes, you can create a system that can follow arbitrary XML or HTML links.  However, REST APIs are being used to build other systems.  Those system require specific functionality from the API at specific points in the interaction (a.k.a.the client workspace).  I haven't seen a working "REST API" that provides a method to derive ALL of the URLs for that timely specific functionality based on a single entry point.

                                              I'm going to give an example of this with a non-existant, theoretical REST API from a company called Metflix (not to be confused with any other APIs, for legal reasons).

                                              (Bear with me here, it's going to take some time to get to the punch line.)

                                              Metflix is a website that has all movies that relate to the Mets football franchise (which of course does not exist, and has no relation to any company what-so-ever).  You can:
                                              • login (metflix.com/login),
                                              • manage your Queue of Mets movies (/myqueue, as a starting point plus management functionality),
                                              • view a list of the latest movies (/movies/),
                                              • view information about a Mets movie (/movies/{id}),
                                              • search for Mets movies (/search?term={searchTerm}). 
                                              Of course there are plenty of other whiz-bang features, but we can limit our discussion to those :).

                                              The Metflix website got so successful, that it created a RESTful API so that other applications can be built around its services.  The URLS of the service just happen to have the same URLs as the site, but are prefixed by '/api'. 

                                              I want to build a fancy Flash UI client for that service, that basically exposes the same services, but just looks much nicer (Note: their affiliate program is fantastic... I'll make a ton of money that way).

                                              My Flash app requires the user to login, then he or she can manage the queue, search for Mets movies, and consequently view details about movies from either the queue or the search results. 

                                              My fancy Flash client will POST to 'metflix.com/api/login', and get a 200 status code and an auth token.  Then it will show your queue, (which as you remember, is found at '/api/myqueue' and of course the auth token has to be used here) in one panel, which has links to the individual movies in the queue, and another panel will show you latest movies (which as you remember is found at '/api/movies') which also has links to movies.  There's also a search box that performs a GET to ('/search?term=' + searchbox.text).

                                              (I almost got to the punchline... wait for it)

                                              The process of linking to invidual movies from the queue, the movie list and search results is RESTful.  You GET a list of movies (name + link) back, and can click on those links to "transition state" to view the movie details.

                                              The problem is that for the sake of my specific requirements, I hardcoded the URLs for the queue, the current movie list and the search box.  I didn't "discover" those URLs based on the result of my login request (which happens to be my bookmark and entry point to the system).  Notice that I also hard-coded the query parameter that needs to be used for my search term. 

                                              Based on my (clearly limited) understanding of REST, all of that hardcoding of URLs in my Flash UI, which is a client of the Metflix.com, is a violation of the HATEOAS/hyptertext constraint.  Based on my (personal, limited) observation, there are no RESTful APIs that implement the hypertext constraint any better. 

                                              Even if I did get back URLs, my Flash would still need to find the current value of a specific URL for a specific task (like the URL for the 'list of current movies', the URL for the 'movies in my queue' and the URL and the name of the query param of the search form).  The Metflix API needs to somehow provide my client with a set of URLs that I need for my next potential logical tasks (my "workspace," if I understandy Roy Fielding correctly).  It also needs to assign a means of of identifying how those URLs map to a specific functionality that's different from the URLs themselves.  For example It's not proper to expect the client to know what '/api/movies' is.  The server needs to provide another piece of well-understood information from which my Flash UI can interpret that the meaning of the '/api/movies' link is 'the current list of movies.'

                                              Websites, unlike REST APIs, do have a clever method of link identification... It's the natural language found between and around the '<a href="..">' and the '</a>' tags.  There's an "interpretation engine" that can understand that natural language, and discover the features of the pages, with the help of a User Agent (such as a web browser).  (BTW, the more I think about it, the more I apprciate th thought put into HTML and the rest of the REST ecosystem).

                                              Is there a clever universal method for identifying ALL appropriate links in a client of a REST API such that you can start with a given URL/bookmark (like login), and not have to hardcode any "workspace" URLs other than the first?  Is this identification process to complex without a human to interpret the meaning of the links? 

                                              Take a look at Craig McLanahan's first message in this thread... IMHO, it has some important clues to these answers :)

                                              Darrel
                                              , does that answer the question satisfactorally?

                                              Roy, if you're reading this, did I get it right this time?

                                              -Solomon Duskis
                                            • Ebenezer Ikonne
                                              ... Are you expecting that a client should guess the next state transition out of the blue? I m not sure this is possible. Some knowledge has to be
                                              Message 22 of 28 , Mar 4, 2009
                                              View Source
                                              • 0 Attachment
                                                --- In rest-discuss@yahoogroups.com, Solomon Duskis <sduskis@...> wrote:
                                                >
                                                > Comments below
                                                >
                                                > On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller <darrel.miller@...>wrote:
                                                >
                                                > >
                                                > > On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...> wrote:
                                                > >
                                                > >> C) Website discover works because there's a human driving the
                                                > >> navigation. REST API discoverability requires a complex "discovery engine"
                                                > >> making REST APIs too complex to discover effectively without that engine.
                                                > >> The barrier to entry is too big,
                                                > >>
                                                > >
                                                > >
                                                > >
                                                > >> __,_._,_
                                                > >>
                                                > >
                                                > > I don't understand why you believe it is difficult to get a client
                                                > > application to discover links. Writing client side code to finding and
                                                > > follow links in an XML or HTML based document is quite trivial.
                                                > >
                                                > > Darrel
                                                > >
                                                >
                                                > Good question Darrel; it's straight to the point :). I hope that this email
                                                > will answer that question. I also hope that this will either prove or
                                                > disprove that I understand what Roy Fielding said in the last email to this
                                                > group.
                                                >
                                                > Yes, you can create a system that can follow *arbitrary *XML or HTML links.
                                                > However, REST APIs are being used to build other systems. Those system
                                                > require *specific functionality* from the API at *specific *points in the
                                                > interaction (a.k.a.the client workspace). I haven't seen a working "REST
                                                > API" that provides a method to derive ALL of the URLs for that timely
                                                > specific functionality based on a single entry point.
                                                >
                                                > I'm going to give an example of this with a non-existant, theoretical REST
                                                > API from a company called Metflix (not to be confused with any other APIs,
                                                > for legal reasons).
                                                >
                                                > (Bear with me here, it's going to take some time to get to the punch line.)
                                                >
                                                > Metflix is a website that has all movies that relate to the Mets football
                                                > franchise (which of course does not exist, and has no relation to any
                                                > company what-so-ever). You can:
                                                >
                                                > - login (metflix.com/login),
                                                > - manage your Queue of Mets movies (/myqueue, as a starting point plus
                                                > management functionality),
                                                > - view a list of the latest movies (/movies/),
                                                > - view information about a Mets movie (/movies/{id}),
                                                > - search for Mets movies (/search?term={searchTerm}).
                                                >
                                                > Of course there are plenty of other whiz-bang features, but we can limit our
                                                > discussion to those :).
                                                >
                                                > The Metflix website got so successful, that it created a RESTful API so that
                                                > other applications can be built around its services. The URLS of the
                                                > service just happen to have the same URLs as the site, but are prefixed by
                                                > '/api'.
                                                >
                                                > I want to build a fancy Flash UI client for that service, that basically
                                                > exposes the same services, but just looks much nicer (Note: their affiliate
                                                > program is fantastic... I'll make a ton of money that way).
                                                >
                                                > My Flash app requires the user to login, then he or she can manage the
                                                > queue, search for Mets movies, and consequently view details about movies
                                                > from either the queue or the search results.
                                                >
                                                > My fancy Flash client will POST to 'metflix.com/api/login', and get a 200
                                                > status code and an auth token. Then it will show your queue, (which as you
                                                > remember, is found at '/api/myqueue' and of course the auth token has to be
                                                > used here) in one panel, which has links to the individual movies in the
                                                > queue, and another panel will show you latest movies (which as you remember
                                                > is found at '/api/movies') which also has links to movies. There's also a
                                                > search box that performs a GET to ('/search?term=' + searchbox.text).
                                                >
                                                > (I almost got to the punchline... wait for it)
                                                >
                                                > The process of linking to invidual movies from the queue, the movie list and
                                                > search results is RESTful. You GET a list of movies (name + link) back, and
                                                > can click on those links to "transition state" to view the movie details.
                                                >
                                                > The problem is that for the sake of my specific requirements, I hardcoded
                                                > the URLs for the queue, the current movie list and the search box. I didn't
                                                > "discover" those URLs based on the result of my login request (which happens
                                                > to be my bookmark and entry point to the system). Notice that I also
                                                > hard-coded the query parameter that needs to be used for my search term.
                                                >
                                                > Based on my (clearly limited) understanding of REST, all of that hardcoding
                                                > of URLs in my Flash UI, which is a client of the Metflix.com, is a violation
                                                > of the HATEOAS/hyptertext constraint. Based on my (personal, limited)
                                                > observation, there are no RESTful APIs that implement the hypertext
                                                > constraint any better.
                                                >
                                                > Even if I did get back URLs, my Flash would still need to find the *current
                                                > value *of *a specific URL *for a specific task (like the URL for the 'list
                                                > of current movies', the URL for the 'movies in my queue' and the URL and the
                                                > name of the query param of the search form). The Metflix API needs to
                                                > somehow provide my client with a set of URLs that I need for my next
                                                > potential logical tasks (my "workspace," if I understandy Roy Fielding
                                                > correctly). It also needs to assign a means of of identifying how those
                                                > URLs map to a specific functionality that's different from the URLs
                                                > themselves. For example It's not proper to expect the client to know what
                                                > '/api/movies' is. The server needs to provide another piece of
                                                > well-understood information from which my Flash UI can *interpret *that the
                                                > meaning of the '/api/movies' link is 'the current list of movies.'
                                                >
                                                > Websites, unlike REST APIs, do have a clever method of link
                                                > identification... It's the natural language found between and around the '<a
                                                > href="..">' and the '</a>' tags. There's an "interpretation engine" that
                                                > can understand that natural language, and discover the features of the
                                                > pages, with the help of a User Agent (such as a web browser). (BTW, the
                                                > more I think about it, the more I apprciate th thought put into HTML and the
                                                > rest of the REST ecosystem).
                                                >
                                                > Is there a clever universal method for identifying ALL appropriate links in
                                                > a client of a REST API such that you can start with a given URL/bookmark
                                                > (like login), and not have to hardcode any "workspace" URLs other than the
                                                > first? Is this identification process to complex without a human to
                                                > interpret the meaning of the links?
                                                >
                                                > Take a look at Craig McLanahan's first message in this thread... IMHO, it
                                                > has some important clues to these answers :)
                                                > *
                                                > Darrel*, does that answer the question satisfactorally?
                                                >
                                                > *Roy*, if you're reading this, did I get it right this time?
                                                >
                                                > -Solomon Duskis
                                                >

                                                Are you expecting that a client should "guess" the next state transition out of the blue? I'm not sure this is possible. Some knowledge has to be provided (I think) out of band that explains "relationships" in some way such that a client can be programmed to traverse the state transitions. The key (in my opinion) is that the out of band information are not URIs but rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships and basically monikers like "self" have meaning within the protocol.

                                                Eb
                                              • Darrel Miller
                                                ... of the URLs ... Here is an experimental api that accesses the MSDN documentation and the community generated content.
                                                Message 23 of 28 , Mar 4, 2009
                                                View Source
                                                • 0 Attachment
                                                  Solomon Duskis wrote:
                                                  > I haven't seen a working "REST API" that provides a method to derive ALL of the URLs 
                                                  > for that timely specific functionality based on a single entry point.


                                                  Here is an experimental api that accesses the MSDN documentation and the community generated content.

                                                  http://lab.msdn.microsoft.com/restapi/

                                                  It uses the XHTML media type. I don't believe you need any other information to start using it.


                                                  Ebenezer Ikonne wrote:
                                                  > The key (in my opinion) is that the out of band information are not URIs but 
                                                  > rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships
                                                  > and basically monikers like "self" have meaning within the protocol.

                                                  Those rel values are not "out of band" they are defined in the Atom spec which is related to the media type that is returned.  To my knowledge if you want a client to interpret your own rel values you have two choices, you can create your own media-type and define the rel values or you can download code (a la AJAX) that knows what to do with those rel values.

                                                  Darrel
                                                • Stefan Tilkov
                                                  You are (almost) right I think. The difference is: Given the representation contains you don t hardcode the string
                                                  Message 24 of 28 , Mar 4, 2009
                                                  View Source
                                                  • 0 Attachment
                                                    You are (almost) right I think. The difference is: Given the
                                                    representation contains

                                                    <link rel="some-concept" ref="/some-uri" />

                                                    you don't hardcode the string "/some-uri" into your client, but rather
                                                    the string "some-concept".

                                                    Of course your program can't interpret new values of rel on the fly
                                                    (unless it's some fancy AI, but let's not get there). You are of
                                                    course better off if you use values for rel that are widely understood
                                                    - this is the reason for efforts like this:

                                                    http://tools.ietf.org/html/draft-nottingham-http-link-header-04

                                                    Stefan
                                                    --
                                                    Stefan Tilkov, http://www.innoq.com/blog/st/



                                                    On 05.03.2009, at 05:03, Solomon Duskis wrote:

                                                    >
                                                    > Comments below
                                                    >
                                                    > On Wed, Mar 4, 2009 at 9:18 PM, Darrel Miller
                                                    > <darrel.miller@...> wrote:
                                                    >
                                                    > On Wed, Mar 4, 2009 at 6:31 AM, Solomon Duskis <sduskis@...>
                                                    > wrote:
                                                    > C) Website discover works because there's a human driving the
                                                    > navigation. REST API discoverability requires a complex "discovery
                                                    > engine" making REST APIs too complex to discover effectively without
                                                    > that engine. The barrier to entry is too big,
                                                    >
                                                    >
                                                    >
                                                    > __,_._,_
                                                    >
                                                    > I don't understand why you believe it is difficult to get a client
                                                    > application to discover links. Writing client side code to finding
                                                    > and follow links in an XML or HTML based document is quite trivial.
                                                    >
                                                    > Darrel
                                                    >
                                                    > Good question Darrel; it's straight to the point :). I hope that
                                                    > this email will answer that question. I also hope that this will
                                                    > either prove or disprove that I understand what Roy Fielding said in
                                                    > the last email to this group.
                                                    >
                                                    > Yes, you can create a system that can follow arbitrary XML or HTML
                                                    > links. However, REST APIs are being used to build other systems.
                                                    > Those system require specific functionality from the API at specific
                                                    > points in the interaction (a.k.a.the client workspace). I haven't
                                                    > seen a working "REST API" that provides a method to derive ALL of
                                                    > the URLs for that timely specific functionality based on a single
                                                    > entry point.
                                                    >
                                                    > I'm going to give an example of this with a non-existant,
                                                    > theoretical REST API from a company called Metflix (not to be
                                                    > confused with any other APIs, for legal reasons).
                                                    >
                                                    > (Bear with me here, it's going to take some time to get to the punch
                                                    > line.)
                                                    >
                                                    > Metflix is a website that has all movies that relate to the Mets
                                                    > football franchise (which of course does not exist, and has no
                                                    > relation to any company what-so-ever). You can:
                                                    > • login (metflix.com/login),
                                                    > • manage your Queue of Mets movies (/myqueue, as a starting point
                                                    > plus management functionality),
                                                    > • view a list of the latest movies (/movies/),
                                                    > • view information about a Mets movie (/movies/{id}),
                                                    > • search for Mets movies (/search?term={searchTerm}).
                                                    > Of course there are plenty of other whiz-bang features, but we can
                                                    > limit our discussion to those :).
                                                    >
                                                    > The Metflix website got so successful, that it created a RESTful API
                                                    > so that other applications can be built around its services. The
                                                    > URLS of the service just happen to have the same URLs as the site,
                                                    > but are prefixed by '/api'.
                                                    >
                                                    > I want to build a fancy Flash UI client for that service, that
                                                    > basically exposes the same services, but just looks much nicer
                                                    > (Note: their affiliate program is fantastic... I'll make a ton of
                                                    > money that way).
                                                    >
                                                    > My Flash app requires the user to login, then he or she can manage
                                                    > the queue, search for Mets movies, and consequently view details
                                                    > about movies from either the queue or the search results.
                                                    >
                                                    > My fancy Flash client will POST to 'metflix.com/api/login', and get
                                                    > a 200 status code and an auth token. Then it will show your queue,
                                                    > (which as you remember, is found at '/api/myqueue' and of course the
                                                    > auth token has to be used here) in one panel, which has links to the
                                                    > individual movies in the queue, and another panel will show you
                                                    > latest movies (which as you remember is found at '/api/movies')
                                                    > which also has links to movies. There's also a search box that
                                                    > performs a GET to ('/search?term=' + searchbox.text).
                                                    >
                                                    > (I almost got to the punchline... wait for it)
                                                    >
                                                    > The process of linking to invidual movies from the queue, the movie
                                                    > list and search results is RESTful. You GET a list of movies (name
                                                    > + link) back, and can click on those links to "transition state" to
                                                    > view the movie details.
                                                    >
                                                    > The problem is that for the sake of my specific requirements, I
                                                    > hardcoded the URLs for the queue, the current movie list and the
                                                    > search box. I didn't "discover" those URLs based on the result of
                                                    > my login request (which happens to be my bookmark and entry point to
                                                    > the system). Notice that I also hard-coded the query parameter that
                                                    > needs to be used for my search term.
                                                    >
                                                    > Based on my (clearly limited) understanding of REST, all of that
                                                    > hardcoding of URLs in my Flash UI, which is a client of the
                                                    > Metflix.com, is a violation of the HATEOAS/hyptertext constraint.
                                                    > Based on my (personal, limited) observation, there are no RESTful
                                                    > APIs that implement the hypertext constraint any better.
                                                    >
                                                    > Even if I did get back URLs, my Flash would still need to find the
                                                    > current value of a specific URL for a specific task (like the URL
                                                    > for the 'list of current movies', the URL for the 'movies in my
                                                    > queue' and the URL and the name of the query param of the search
                                                    > form). The Metflix API needs to somehow provide my client with a
                                                    > set of URLs that I need for my next potential logical tasks (my
                                                    > "workspace," if I understandy Roy Fielding correctly). It also
                                                    > needs to assign a means of of identifying how those URLs map to a
                                                    > specific functionality that's different from the URLs themselves.
                                                    > For example It's not proper to expect the client to know what '/api/
                                                    > movies' is. The server needs to provide another piece of well-
                                                    > understood information from which my Flash UI can interpret that the
                                                    > meaning of the '/api/movies' link is 'the current list of movies.'
                                                    >
                                                    > Websites, unlike REST APIs, do have a clever method of link
                                                    > identification... It's the natural language found between and around
                                                    > the '<a href="..">' and the '</a>' tags. There's an "interpretation
                                                    > engine" that can understand that natural language, and discover the
                                                    > features of the pages, with the help of a User Agent (such as a web
                                                    > browser). (BTW, the more I think about it, the more I apprciate th
                                                    > thought put into HTML and the rest of the REST ecosystem).
                                                    >
                                                    > Is there a clever universal method for identifying ALL appropriate
                                                    > links in a client of a REST API such that you can start with a given
                                                    > URL/bookmark (like login), and not have to hardcode any "workspace"
                                                    > URLs other than the first? Is this identification process to
                                                    > complex without a human to interpret the meaning of the links?
                                                    >
                                                    > Take a look at Craig McLanahan's first message in this thread...
                                                    > IMHO, it has some important clues to these answers :)
                                                    >
                                                    > Darrel, does that answer the question satisfactorally?
                                                    >
                                                    > Roy, if you're reading this, did I get it right this time?
                                                    >
                                                    > -Solomon Duskis
                                                    >
                                                    >
                                                    > <!-- #ygrp-mkp{ border: 1px solid #d8d8d8; font-family: Arial;
                                                    > margin: 14px 0px; padding: 0px 14px; } #ygrp-mkp hr{ border: 1px
                                                    > solid #d8d8d8; } #ygrp-mkp #hd{ color: #628c2a; font-size: 85%; font-
                                                    > weight: bold; line-height: 122%; margin: 10px 0px; } #ygrp-mkp
                                                    > #ads{ margin-bottom: 10px; } #ygrp-mkp .ad{ padding: 0 0; } #ygrp-
                                                    > mkp .ad a{ color: #0000ff; text-decoration: none; } --> <!-- #ygrp-
                                                    > sponsor #ygrp-lc{ font-family: Arial; } #ygrp-sponsor #ygrp-lc
                                                    > #hd{ margin: 10px 0px; font-weight: bold; font-size: 78%; line-
                                                    > height: 122%; } #ygrp-sponsor #ygrp-lc .ad{ margin-bottom: 10px;
                                                    > padding: 0 0; } --> <!-- #ygrp-mlmsg {font-size:13px; font-family:
                                                    > arial,helvetica,clean,sans-serif;*font-size:small;*font:x-small;}
                                                    > #ygrp-mlmsg table {font-size:inherit;font:100%;} #ygrp-mlmsg select,
                                                    > input, textarea {font:99% arial,helvetica,clean,sans-serif;} #ygrp-
                                                    > mlmsg pre, code {font:115% monospace;*font-size:100%;} #ygrp-mlmsg *
                                                    > {line-height:1.22em;} #ygrp-text{ font-family: Georgia; } #ygrp-
                                                    > text p{ margin: 0 0 1em 0; } dd.last p a { font-family: Verdana;
                                                    > font-weight: bold; } #ygrp-vitnav{ padding-top: 10px; font-family:
                                                    > Verdana; font-size: 77%; margin: 0; } #ygrp-vitnav a{ padding: 0
                                                    > 1px; } #ygrp-mlmsg #logo{ padding-bottom: 10px; } #ygrp-reco
                                                    > { margin-bottom: 20px; padding: 0px; } #ygrp-reco #reco-head { font-
                                                    > weight: bold; color: #ff7900; } #reco-category{ font-size: 77%; }
                                                    > #reco-desc{ font-size: 77%; } #ygrp-vital a{ text-decoration:
                                                    > none; } #ygrp-vital a:hover{ text-decoration: underline; } #ygrp-
                                                    > sponsor #ov ul{ padding: 0 0 0 8px; margin: 0; } #ygrp-sponsor #ov
                                                    > li{ list-style-type: square; padding: 6px 0; font-size: 77%; } #ygrp-
                                                    > sponsor #ov li a{ text-decoration: none; font-size: 130%; } #ygrp-
                                                    > sponsor #nc{ background-color: #eee; margin-bottom: 20px;
                                                    > padding: 0 8px; } #ygrp-sponsor .ad{ padding: 8px 0; } #ygrp-
                                                    > sponsor .ad #hd1{ font-family: Arial; font-weight: bold; color:
                                                    > #628c2a; font-size: 100%; line-height: 122%; } #ygrp-sponsor .ad
                                                    > a{ text-decoration: none; } #ygrp-sponsor .ad a:hover{ text-
                                                    > decoration: underline; } #ygrp-sponsor .ad p{ margin: 0; } o{font-
                                                    > size: 0; } .MsoNormal{ margin: 0 0 0 0; } #ygrp-text tt{ font-size:
                                                    > 120%; } blockquote{margin: 0 0 0 4px;} .replbq{margin:4} dd.last p
                                                    > span { margin-right: 10px; font-family: Verdana; font-weight:
                                                    > bold; } dd.last p span.yshortcuts { margin-right: 0; } div.photo-
                                                    > title a, div.photo-title a:active, div.photo-title a:hover,
                                                    > div.photo-title a:visited { text-decoration: none; } div.file-title
                                                    > a, div.file-title a:active, div.file-title a:hover, div.file-title
                                                    > a:visited { text-decoration: none; } #ygrp-msg p { clear: both;
                                                    > padding: 15px 0 3px 0; overflow: hidden; } #ygrp-msg p span { color:
                                                    > #1E66AE; font-weight: bold; } div#ygrp-mlmsg #ygrp-msg p a
                                                    > span.yshortcuts { font-family: Verdana; font-size: 10px; font-
                                                    > weight: normal; } #ygrp-msg p a { font-family: Verdana; font-size:
                                                    > 10px; } #ygrp-mlmsg a { color: #1E66AE; } div.attach-table div div a
                                                    > { text-decoration: none; } div.attach-table { width: 400px; } -->
                                                  • Solomon Duskis
                                                    *RE: XHTML *It looks like a promising foundation for RESTful API Media Types. You have a whole bunch of class= on your tags (plus other
                                                    Message 25 of 28 , Mar 5, 2009
                                                    View Source
                                                    • 0 Attachment
                                                      RE: XHTML
                                                      It looks like a promising foundation for RESTful API Media Types.  You have a whole bunch of class="<some identifier>" on your <a> tags (plus other tags) that a programmatic client can use to identify the meaning link (rather than relying on the href itself). 

                                                      I do think that HTML is the media to emulate.  "class" is used successfully to perform the kind of semantic markup that atom's "rel" has.  "class" can also be multi-valued (which I don't know if that's possible with "rel") and is currently used by programmatic constructs to infer meaning outside of the href.  "class" also has HTML siblings in the task of identification.  There's also the "id" tag in the "a" element, the body of the "a" element, and "<label for=''>...</label>" for form elements.  RESTful API Media Types need a way to integrate these types of tactics in a consistent way.

                                                      Beyond the Media Type issues, another thing that needs to be explored is how to use this information the the client side for non-browser clients.  The programmatic constructs that use "class" (such as JavaScript, and even CSS) usually fall under the role of code-on-demand, but the general techniques can be used for programmatic constructs that fill the role of remote client.  Once we have a consistent approach to Media Types, we can start constructing "User Agent" APIs that ease the task of traversing specific RESTful API Media Types that share common elements of semantic markup. 

                                                      RE: I don't believe you need any other information to start using it.

                                                      Before a programmatic client can perform a specific task it must either know a single "class" value , or a set of "class" values to follow.  IMHO, that's shared "out of band" information, but it's not driving the interaction; meaning those semantics are the crux of what you need to know to interact, but they don't define lower-level URI construction semantics.  A bookmark + shared media types + shared semantics should provide a way for the client can discover the specific resources it needs from the server.

                                                      you can create your own media-type and define the rel values 

                                                      I'm not going to put words in your mouth, but it sounds like there needs to be a shared understanding of semantics.  That shared understanding can come from a community consensus like Stefan Tikolov suggests:

                                                      Of course your program can't interpret new values of rel on the fly (unless it's some fancy AI, but let's not get there). You are of
                                                      course better off if you use values for rel that are widely understood - this is the reason for efforts like this:

                                                      http://tools.ietf.org/html/draft-nottingham-http-link-header-04

                                                      It's also perfectly legitimate for a RESTful API to create its own dictionary of values, along with its own Media Types.  It may also provide a few entry points for different client types.  Those should the likely be the only items on a RESTful API documentation page :).  (It's also likely that the API will have a set of example URLs to show some specific functionality, but should discourage clients from using those URLs directly, and encourage the use of semantics)

                                                      or you can download code (a la AJAX) that knows what to do with those rel values that knows what to do with those rel values.

                                                      I agree that this is a great option and should be explored, especially outside the generic web browser.  Like I said earlier, I can see a great place for "User Agent" platforms that know about a common Media Type rules and knows how run ubiquitous scripting languages... More on that later :)


                                                      Thanks for the discussion guys!  This has been greatly enlightening.

                                                      -Solomon

                                                      On Thu, Mar 5, 2009 at 12:50 AM, Darrel Miller <darrel.miller@...> wrote:

                                                      Solomon Duskis wrote:
                                                      > I haven't seen a working "REST API" that provides a method to derive ALL of the URLs 
                                                      > for that timely specific functionality based on a single entry point.


                                                      Here is an experimental api that accesses the MSDN documentation and the community generated content.

                                                      http://lab.msdn.microsoft.com/restapi/

                                                      It uses the XHTML media type. I don't believe you need any other information to start using it.


                                                      Ebenezer Ikonne wrote:
                                                      > The key (in my opinion) is that the out of band information are not URIs but 
                                                      > rather "identifiers" for relationships e.g. Atom uses "rel" to indicate relationships
                                                      > and basically monikers like "self" have meaning within the protocol.

                                                      Those rel values are not "out of band" they are defined in the Atom spec which is related to the media type that is returned.  To my knowledge if you want a client to interpret your own rel values you have two choices, you can create your own media-type and define the rel values or you can download code (a la AJAX) that knows what to do with those rel values.

                                                      Darrel

                                                    • Ebenezer Ikonne
                                                      ... Well in a sense they are, because the protocol exists in text that is outside of the client. The client is not determining what rel inline, its
                                                      Message 26 of 28 , Mar 5, 2009
                                                      View Source
                                                      • 0 Attachment
                                                        > Those rel values are not "out of band" they are defined in the Atom spec
                                                        > which is related to the media type that is returned. To my knowledge if you
                                                        > want a client to interpret your own rel values you have two choices, you can
                                                        > create your own media-type and define the rel values or you can download
                                                        > code (a la AJAX) that knows what to do with those rel values.
                                                        >
                                                        > Darrel
                                                        >

                                                        Well in a sense they are, because the protocol exists in text that is outside of the client. The client is not determining what "rel" inline, its programmed with a priori knowledge of the transitions. provided by all "rel" values.

                                                        Having said that, I think we're splitting hairs here. :)
                                                      • Darrel Miller
                                                        Here is an interesting survey of rel values in use on the web. http://blog.unto.net/web/a-survey-of-rel-values-on-the-web/ ... Yes the client must understand
                                                        Message 27 of 28 , Mar 5, 2009
                                                        View Source
                                                        • 0 Attachment
                                                          Here is an interesting survey of rel values in use on the web.

                                                          http://blog.unto.net/web/a-survey-of-rel-values-on-the-web/
                                                          Excerpt:
                                                          >  found a staggering 1.8M unique rel value strings in use, with many used only once or
                                                          > twice across all the web. In fact, the top 6 most-frequently-used rel values accounted
                                                          > for 80% of all usage, and the top 11 alone were responsible for 90% of all usage.


                                                          On Thu, Mar 5, 2009 at 7:39 AM, Ebenezer Ikonne <amaeze@...> wrote:
                                                          >
                                                          > Well in a sense they are, because the protocol exists in text that is outside of the client.
                                                          > The client is not determining what "rel" inline, its programmed with a priori knowledge of the
                                                          > transitions. provided by all "rel" values.
                                                          >

                                                          Yes the client must understand the media type before hand.  However
                                                          the significant difference is that when the client follows a link, the
                                                          media-type is in the header of the response.  The client knows how to
                                                          parse the message based only on the content of the message and its
                                                          prior knowledge of the media type.  In so many so called "RESTful"
                                                          API's that I see the client retrieves application/xml from endpoint
                                                          http://site.org/xyz and it must know that the application/xml at this
                                                          endpoint contains a specific vocabulary.

                                                          Darrel
                                                        • Ebenezer Ikonne
                                                          ... I think we are in some agreement here. Now the debate for whether to use generic media-types versus specific media-types is slightly different (IMO). I
                                                          Message 28 of 28 , Mar 5, 2009
                                                          View Source
                                                          • 0 Attachment
                                                            > Yes the client must understand the media type before hand. �However
                                                            > the significant difference is that when the client follows a link, the
                                                            > media-type is in the header of the response. �The client knows how to
                                                            > parse the message based only on the content of the message and its
                                                            > prior knowledge of the media type. �In so many so called "RESTful"
                                                            > API's that I see the client retrieves application/xml from endpoint
                                                            > http://site.org/xyz and it must know that the application/xml at this
                                                            > endpoint contains a specific vocabulary.
                                                            >
                                                            > Darrel
                                                            >

                                                            I think we are in some agreement here. Now the debate for whether to use generic media-types versus specific media-types is slightly different (IMO). I believe in specific media-types, but in both cases, a priori is still required. The flexibility of the client is severely hampered when using generic media-types.

                                                            Eb
                                                          Your message has been successfully submitted and would be delivered to recipients shortly.