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

Re: Unable to deliver your message

Expand Messages
  • mike amundsen
    FWIW, I prefer to treat partial updates as if they are a different resource than the full update. That means I use a different URL for partial updates. It
    Message 1 of 9 , Jan 2, 2008
    • 0 Attachment
      FWIW, I prefer to treat partial updates as if they are a different
      resource than the full update. That means I use a different URL for
      partial updates. It keeps my server-side work clean, IMHO.

      PUT /resource/{id}
      <resource>
      <foo>1</foo>
      <bar>1</bar>
      </resource>

      PUT /resource/{id}/foo
      <foo>2</foo>

      Now I know that my server-side validation will be straightforward (no
      accounting for possible optional items or 'fill in with existing
      values' things to deal with). This also makes it possible for me to
      create different access rules for partial updates (maybe only admins
      can do partials, etc.).

      MikeA

      > On Jan 2, 2008 12:02 PM, Ebenezer Ikonne <amaeze@...> wrote:
      > >
      > >
      > > --- In rest-discuss@yahoogroups.com, Subbu Allamaraju
      > > <subbu.allamaraju@...> wrote:
      > > >
      > > > Why not just use <bar> as the document root element in the second case
      > > > below? In that case, a PUT with root element foo would be a
      > > > replacement request for the entire resource, where as a PUT for root
      > > > element bar would imply a replacement of bar. Allowing such fine-
      > > > grained updates may not always be feasible/desirable though.
      > > >
      > >
      > >
      > > I think this the approach that I would follow. To give a more concrete
      > > example, if I have:
      > >
      > > <itemResource>
      > >
      > > <item>Dodge Stratus</item>
      > >
      > > <itemDesc>Light Green</itemDesc>
      > >
      > > </itemResource>
      > >
      > > and I wanted to change "itemDesc", then arepresentation I thought I
      > > could send via PUT would be
      > >
      > > <itemDesc> Light Blue </itemDesc>
      > >
      > > If I am missing something, let me know.
      > >
      > >
      > >
      > >
      > >
      > >
      > > Yahoo! Groups Links
      > >
      > >
      > >
      > >
      >
      >
      >
      > --
      > mca
      > "In a time of universal deceit, telling the truth becomes a
      > revolutionary act. " (George Orwell)
      >
      >



      --
      mca
      "In a time of universal deceit, telling the truth becomes a
      revolutionary act. " (George Orwell)
    • Subbu Allamaraju
      ... Exactly. That s what I meant. Subbu http://subbu.org
      Message 2 of 9 , Jan 2, 2008
      • 0 Attachment
        > FWIW, I prefer to treat partial updates as if they are a different
        > resource than the full update. That means I use a different URL for
        > partial updates. It keeps my server-side work clean, IMHO.
        >
        > PUT /resource/{id}
        > <resource>
        > <foo>1</foo>
        > <bar>1</bar>
        > </resource>
        >
        > PUT /resource/{id}/foo
        > <foo>2</foo>

        Exactly. That's what I meant.

        Subbu
        http://subbu.org


        > Now I know that my server-side validation will be straightforward (no
        > accounting for possible optional items or 'fill in with existing
        > values' things to deal with). This also makes it possible for me to
        > create different access rules for partial updates (maybe only admins
        > can do partials, etc.).
        >
        > MikeA
        >
        >> On Jan 2, 2008 12:02 PM, Ebenezer Ikonne <amaeze@...> wrote:
        >>>
        >>>
        >>> --- In rest-discuss@yahoogroups.com, Subbu Allamaraju
        >>> <subbu.allamaraju@...> wrote:
        >>>>
        >>>> Why not just use <bar> as the document root element in the second
        >>>> case
        >>>> below? In that case, a PUT with root element foo would be a
        >>>> replacement request for the entire resource, where as a PUT for
        >>>> root
        >>>> element bar would imply a replacement of bar. Allowing such fine-
        >>>> grained updates may not always be feasible/desirable though.
        >>>>
        >>>
        >>>
        >>> I think this the approach that I would follow. To give a more
        >>> concrete
        >>> example, if I have:
        >>>
        >>> <itemResource>
        >>>
        >>> <item>Dodge Stratus</item>
        >>>
        >>> <itemDesc>Light Green</itemDesc>
        >>>
        >>> </itemResource>
        >>>
        >>> and I wanted to change "itemDesc", then arepresentation I thought I
        >>> could send via PUT would be
        >>>
        >>> <itemDesc> Light Blue </itemDesc>
        >>>
        >>> If I am missing something, let me know.
        >>>
        >>>
        >>>
        >>>
        >>>
        >>>
        >>> Yahoo! Groups Links
        >>>
        >>>
        >>>
        >>>
        >>
        >>
        >>
        >> --
        >> mca
        >> "In a time of universal deceit, telling the truth becomes a
        >> revolutionary act. " (George Orwell)
        >>
        >>
        >
        >
        >
        > --
        > mca
        > "In a time of universal deceit, telling the truth becomes a
        > revolutionary act. " (George Orwell)
        >
        >
        >
        > Yahoo! Groups Links
        >
        >
        >
      • Ebenezer Ikonne
        I like this from an implementation perspective - driving everything via resources and the URI is powerful. However, when many properties can be modified,
        Message 3 of 9 , Jan 2, 2008
        • 0 Attachment
          I like this from an implementation perspective - driving everything via
          resources and the URI is powerful. However, when "many" properties can
          be modified, the server-side implementation can begin to get very
          kludgy.


          --- In rest-discuss@yahoogroups.com, "mike amundsen" <mamund@...> wrote:
          >
          > FWIW, I prefer to treat partial updates as if they are a different
          > resource than the full update. That means I use a different URL for
          > partial updates. It keeps my server-side work clean, IMHO.
          >
          > PUT /resource/{id}
          > <resource>
          > <foo>1</foo>
          > <bar>1</bar>
          > </resource>
          >
          > PUT /resource/{id}/foo
          > <foo>2</foo>
          >
          > Now I know that my server-side validation will be straightforward (no
          > accounting for possible optional items or 'fill in with existing
          > values' things to deal with). This also makes it possible for me to
          > create different access rules for partial updates (maybe only admins
          > can do partials, etc.).
          >
          > MikeA
          >
          > > On Jan 2, 2008 12:02 PM, Ebenezer Ikonne amaeze@... wrote:
          > > >
          > > >
          > > > --- In rest-discuss@yahoogroups.com, Subbu Allamaraju
          > > > subbu.allamaraju@ wrote:
          > > > >
          > > > > Why not just use <bar> as the document root element in the
          second case
          > > > > below? In that case, a PUT with root element foo would be a
          > > > > replacement request for the entire resource, where as a PUT for
          root
          > > > > element bar would imply a replacement of bar. Allowing such
          fine-
          > > > > grained updates may not always be feasible/desirable though.
          > > > >
          > > >
          > > >
          > > > I think this the approach that I would follow. To give a more
          concrete
          > > > example, if I have:
          > > >
          > > > <itemResource>
          > > >
          > > > <item>Dodge Stratus</item>
          > > >
          > > > <itemDesc>Light Green</itemDesc>
          > > >
          > > > </itemResource>
          > > >
          > > > and I wanted to change "itemDesc", then arepresentation I thought
          I
          > > > could send via PUT would be
          > > >
          > > > <itemDesc> Light Blue </itemDesc>
          > > >
          > > > If I am missing something, let me know.
          > > >
          > > >
          > > >
          > > >
          > > >
          > > >
          > > > Yahoo! Groups Links
          > > >
          > > >
          > > >
          > > >
          > >
          > >
          > >
          > > --
          > > mca
          > > "In a time of universal deceit, telling the truth becomes a
          > > revolutionary act. " (George Orwell)
          > >
          > >
          >
          >
          >
          > --
          > mca
          > "In a time of universal deceit, telling the truth becomes a
          > revolutionary act. " (George Orwell)
          >
        • Elliotte Rusty Harold
          ... It s doable but what of you need to update 6 out of 12 parts? I suppose you could define the partial URLs as query strings easily enough. -- Elliotte Rusty
          Message 4 of 9 , Jan 2, 2008
          • 0 Attachment
            mike amundsen wrote:
            > FWIW, I prefer to treat partial updates as if they are a different
            > resource than the full update. That means I use a different URL for
            > partial updates. It keeps my server-side work clean, IMHO.
            >
            > PUT /resource/{id}
            > <resource>
            > <foo>1</foo>
            > <bar>1</bar>
            > </resource>
            >
            > PUT /resource/{id}/foo
            > <foo>2</foo>
            >

            It's doable but what of you need to update 6 out of 12 parts? I suppose
            you could define the partial URLs as query strings easily enough.


            --
            Elliotte Rusty Harold elharo@...
            Java I/O 2nd Edition Just Published!
            http://www.cafeaulait.org/books/javaio2/
            http://www.amazon.com/exec/obidos/ISBN=0596527500/ref=nosim/cafeaulaitA/
          • mike amundsen
            John: Yep. ETags and catch stale/lost/double updates. But you also bring up a good point (I think I also covered in this thread) on dependent fields. In some
            Message 5 of 9 , Jan 7, 2008
            • 0 Attachment
              John:

              Yep. ETags and catch stale/lost/double updates. But you also bring up
              a good point (I think I also covered in this thread) on dependent
              fields. In some cases, it will be important to define the update
              resource to include more than one element, even if the update involves
              changing just one element. For example, to update the
              BillingContactPhone element, you might need to use the
              BillingContactAddress element and fill in several required elements.
              This helps with resource integrity at another level.

              MikeA

              On Jan 7, 2008 8:23 AM, John F Schlesinger <jschlesinger@...> wrote:
              >
              > Dear Mike,
              > Yes, this is the lost update problem (we used to call it the double update
              > problem).
              >
              > The update should include all the values on which it depends (usually the
              > values that are changed, but could include others, even others from
              > different resources). The precondition for the operation is that these
              > values have not changed. It does not matter if the resources have a later
              > timestamp so long as this precondition holds.
              >
              > This moves the precondition from being implicit to one given by the client
              > (the 'before' values).
              >
              > Of course, the server can also have its own preconditions, but these are
              > there whatever the mechanism for preventing double updates.
              >
              > If you are putting the client's precondition in the ETags, then that does
              > indeed solve the problem.
              >
              > John Schlesinger
              >
              >
              >
              > ----- Original Message ----
              > From: mike amundsen <mamund@...>
              > To: John Schlesinger <jschlesinger@...>
              > Sent: Monday, January 7, 2008 12:55:31 PM
              > Subject: Re: Unable to deliver your message
              >
              > John:
              >
              > If i understand your post,this has to do with the "lost update
              > problem[1]." I use ETags to handle that.
              >
              > [1] Detecting the Lost Update Problem Using Unreserved Checkout
              > http://www.w3.org/1999/04/Editing/
              >
              > MikeA
              >
              > On Jan 7, 2008 7:15 AM, John Schlesinger <jschlesinger@...> wrote:
              > > --- In rest-discuss@yahoogroups.com, "mike amundsen" <mamund@...> wrote:
              > > >
              > > > FWIW, I prefer to treat partial updates as if they are a different
              > > > resource than the full update. That means I use a different URL for
              > > > partial updates. It keeps my server-side work clean, IMHO.
              > > >
              > > > PUT /resource/{id}
              > > > <resource>
              > > > <foo>1</foo>
              > > > <bar>1</bar>
              > > > </resource>
              > > >
              > > > PUT /resource/{id}/foo
              > > > <foo>2</foo>
              > > >
              > >
              > > Would it not be safer to include the 'before' and 'after' values of
              > > this change? Typically, when handling changes from a large number of
              > > clients, it is safe to compare the 'before' version of the values to
              > > be changed with the values currently stored. If they are different,
              > > the change should be rejected. If they are the same, the change can be
              > > applied.
              > >
              > > The thinking behind this approach is that a change may depend on the
              > > current values. If the client and the database disagree on the current
              > > state of the resource, then this state transition may not be valid.
              > >
              > > Of course, if the stored value in the database is the same as the
              > > 'after' value, then rejecting the change makes no difference - it has
              > > the same effect as making the change (with some side effect
              > > differences, for example if the change date is stored in the database).
              > >
              > > John Schlesinger
              > >
              > >
              >
              >
              >
              > --
              > mca
              > "In a time of universal deceit, telling the truth becomes a
              > revolutionary act. " (George Orwell)
              >
              >



              --
              mca
              "In a time of universal deceit, telling the truth becomes a
              revolutionary act. " (George Orwell)
            • mike amundsen
              Message 6 of 9 , Sep 28, 2008
              • 0 Attachment
                > Sounds to me like you have defined a "delete-event" resource that
                > needs to be POSTed to the server
                >
                > POST /delete-events/{id}
                > <reason>xcxcccccc</reason>
                >
                > Some possible advantages:
                > - you can validate the "delete-event" document and deny the delete if
                > it is invalid
                > - you can (at some future date) include additional information in the
                > "delete-event" document w/o the need to change the link/URI rules
                > - you can maintain a list of delete-event records for auditing
                > - if your system get very large, this model would allow for delays
                > between the request for delete and the actual delete w/o slowing
                > client-server interaction
                >
                > mca
                > http://amundsen.com/blog/
                >
                >
                >
                >
                > On Sat, Sep 27, 2008 at 04:50, yaoyaoo2000 <yaoyaoo2000@...> wrote:
                >> i'm designing restful api for an event website.
                >>
                >> one can post to api.xxx.com/events to create a new event
                >> put to api.xxx.com/event/xxx to update info of an event
                >>
                >> delete to api.xxx.com/event/xxx to delete an event
                >>
                >> of course only the creator of the event can delete it. and i want the
                >> creator to give the reason when he delete the event, how should I do this:
                >> 1. add 'reason' in header
                >> or 2. require an xml entry containing reason when delete event?
                >>
                >>
                >> which way is prefered? many thanks
                >>
                >>
              • Subbu Allamaraju
                More broadly speaking, such a sidekick could be used for a number of other use cases where the HTTP s uniform interface is inadequate. In this particular use
                Message 7 of 9 , Sep 29, 2008
                • 0 Attachment
                  More broadly speaking, such a sidekick could be used for a number of
                  other use cases where the HTTP's uniform interface is inadequate.

                  In this particular use case, using a sidekick resource to delete a
                  resource as suggested by Mike has some limitations worth noting:

                  a. Can't implement conditional DELETEs
                  b. Since caches won't see the DELETE, they won't flush the resource.

                  Subbu
                  http://subbu.org

                  On Sep 28, 2008, at 6:12 PM, mike amundsen wrote:

                  > > Sounds to me like you have defined a "delete-event" resource that
                  > > needs to be POSTed to the server
                  > >
                  > > POST /delete-events/{id}
                  > > <reason>xcxcccccc</reason>
                  > >
                  > > Some possible advantages:
                  > > - you can validate the "delete-event" document and deny the delete
                  > if
                  > > it is invalid
                  > > - you can (at some future date) include additional information in
                  > the
                  > > "delete-event" document w/o the need to change the link/URI rules
                  > > - you can maintain a list of delete-event records for auditing
                  > > - if your system get very large, this model would allow for delays
                  > > between the request for delete and the actual delete w/o slowing
                  > > client-server interaction
                  > >
                  > > mca
                  > > http://amundsen.com/blog/
                  > >
                  > >
                  > >
                  > >
                  > > On Sat, Sep 27, 2008 at 04:50, yaoyaoo2000
                  > <yaoyaoo2000@...> wrote:
                  > >> i'm designing restful api for an event website.
                  > >>
                  > >> one can post to api.xxx.com/events to create a new event
                  > >> put to api.xxx.com/event/xxx to update info of an event
                  > >>
                  > >> delete to api.xxx.com/event/xxx to delete an event
                  > >>
                  > >> of course only the creator of the event can delete it. and i want
                  > the
                  > >> creator to give the reason when he delete the event, how should I
                  > do this:
                  > >> 1. add 'reason' in header
                  > >> or 2. require an xml entry containing reason when delete event?
                  > >>
                  > >>
                  > >> which way is prefered? many thanks
                  > >>
                  > >>
                  >
                  > <!-- #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; } #ygrp-tpmsgs{ font-family: Arial;
                  > clear: both; } #ygrp-vitnav{ padding-top: 10px; font-family:
                  > Verdana; font-size: 77%; margin: 0; } #ygrp-vitnav a{ padding: 0
                  > 1px; } #ygrp-actbar{ clear: both; margin: 25px 0; white-
                  > space:nowrap; color: #666; text-align: right; } #ygrp-
                  > actbar .left{ float: left; white-space:nowrap; } .bld{font-
                  > weight:bold;} #ygrp-grft{ font-family: Verdana; font-size: 77%;
                  > padding: 15px 0; } #ygrp-ft{ font-family: verdana; font-size: 77%;
                  > border-top: 1px solid #666; padding: 5px 0; } #ygrp-mlmsg
                  > #logo{ padding-bottom: 10px; } #ygrp-reco { margin-bottom: 20px;
                  > padding: 0px; } #ygrp-reco #reco-head { font-weight: bold; color:
                  > #ff7900; } #reco-grpname{ font-weight: bold; margin-top: 10px; }
                  > #reco-category{ font-size: 77%; } #reco-desc{ font-size: 77%; }
                  > #ygrp-vital{ background-color: #e0ecee; margin-bottom: 20px;
                  > padding: 2px 0 8px 8px; } #ygrp-vital #vithd{ font-size: 77%; font-
                  > family: Verdana; font-weight: bold; color: #333; text-transform:
                  > uppercase; } #ygrp-vital ul{ padding: 0; margin: 2px 0; } #ygrp-
                  > vital ul li{ list-style-type: none; clear: both; border: 1px solid
                  > #e0ecee; } #ygrp-vital ul li .ct{ font-weight: bold; color: #ff7900;
                  > float: right; width: 2em; text-align:right; padding-right: .5em; }
                  > #ygrp-vital ul li .cat{ font-weight: bold; } #ygrp-vital a{ text-
                  > decoration: none; } #ygrp-vital a:hover{ text-decoration:
                  > underline; } #ygrp-sponsor #hd{ color: #999; font-size: 77%; } #ygrp-
                  > sponsor #ov{ padding: 6px 13px; background-color: #e0ecee; margin-
                  > bottom: 20px; } #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} -->
                • mike amundsen
                  I thought about this DELETE w/ notation pattern some more and worked up another possible solution that *does* support conditional DELETE and proper cache
                  Message 8 of 9 , Oct 1, 2008
                  • 0 Attachment
                    I thought about this DELETE w/ notation pattern some more and worked
                    up another possible solution that *does* support conditional DELETE
                    and proper cache invalidation.

                    You could implement a two-step process:
                    1 - create a "delete-reason" resource (PUT /delete-reasons/{item-id})
                    with the proper body.
                    2 - do the actual DELETE (DELETE /items/{id}). The server can check
                    for the "delete-reason" and, if not found, throw a 400 (possibly
                    424-failed dependency).

                    The downside is that it takes two steps. However, it does restore
                    proper support for the DELETE method.

                    mca
                    http://amundsen.com/blog/




                    On Mon, Sep 29, 2008 at 13:37, Subbu Allamaraju <subbu@...> wrote:
                    > More broadly speaking, such a sidekick could be used for a number of other
                    > use cases where the HTTP's uniform interface is inadequate.
                    >
                    > In this particular use case, using a sidekick resource to delete a resource
                    > as suggested by Mike has some limitations worth noting:
                    >
                    > a. Can't implement conditional DELETEs
                    > b. Since caches won't see the DELETE, they won't flush the resource.
                    >
                    > Subbu
                    > http://subbu.org
                    >
                    > On Sep 28, 2008, at 6:12 PM, mike amundsen wrote:
                    >
                    >> > Sounds to me like you have defined a "delete-event" resource that
                    >> > needs to be POSTed to the server
                    >> >
                    >> > POST /delete-events/{id}
                    >> > <reason>xcxcccccc</reason>
                    >> >
                    >> > Some possible advantages:
                    >> > - you can validate the "delete-event" document and deny the delete if
                    >> > it is invalid
                    >> > - you can (at some future date) include additional information in the
                    >> > "delete-event" document w/o the need to change the link/URI rules
                    >> > - you can maintain a list of delete-event records for auditing
                    >> > - if your system get very large, this model would allow for delays
                    >> > between the request for delete and the actual delete w/o slowing
                    >> > client-server interaction
                    >> >
                    >> > mca
                    >> > http://amundsen.com/blog/
                    >> >
                    >> >
                    >> >
                    >> >
                    >> > On Sat, Sep 27, 2008 at 04:50, yaoyaoo2000 <yaoyaoo2000@...>
                    >> > wrote:
                    >> >> i'm designing restful api for an event website.
                    >> >>
                    >> >> one can post to api.xxx.com/events to create a new event
                    >> >> put to api.xxx.com/event/xxx to update info of an event
                    >> >>
                    >> >> delete to api.xxx.com/event/xxx to delete an event
                    >> >>
                    >> >> of course only the creator of the event can delete it. and i want the
                    >> >> creator to give the reason when he delete the event, how should I do
                    >> >> this:
                    >> >> 1. add 'reason' in header
                    >> >> or 2. require an xml entry containing reason when delete event?
                    >> >>
                    >> >>
                    >> >> which way is prefered? many thanks
                    >> >>
                    >> >>
                  • mike amundsen
                    Message 9 of 9 , Apr 8, 2010
                    • 0 Attachment
                      > Thanks for the feedback. I appreciate the time you spent to provide me
                      > with good suggestions.
                      >
                      > I see your point about the overall presentation. This short blog post
                      > skips quite a bit when attempting to educate users on the basics of
                      > REST. Also, I received feedback from others on the possibility that
                      > this particular posting doesn't do enough to clear up the issue of
                      > RPC-like approaches to implementing web interfaces. In fact, a longer
                      > draft of this material included an additional section directly
                      > addressing typical RPC ways to express the service. I actually have an
                      > example SOAP implementation and an example RPC-over-HTTP
                      > implementation, but skipped that in the blog as it too long for this
                      > medium.
                      >
                      > Again, thanks for the helpful feedback and suggestions.
                      >
                      > mca
                      > http://amundsen.com/blog/
                      >
                      >
                      >
                      >
                      > On Thu, Apr 8, 2010 at 09:05, William Martinez Pomares
                      > <wmartinez@...> wrote:
                      >> Ok Mike.
                      >> I've read it and it seems a very simple example that shows the important, core aspects of media type definition. I also noticed you were following Roy's rant guide (I mean, the guide in the rant :D ).
                      >> BTW, Antonio's point about multi protocols should be discussed a little bit in another comment.
                      >>
                      >> But now on this one: I read it and was able to understand the intention, although it was not explicit. If I change my REST knowledge, reducing it to a that of an RPC developer that knows REST is good and his boss told him to implement, quick and dirty, a REST API, I may have problems. I will be probably driven to think I'm defining a mapping for my RPC calls.
                      >>
                      >> So, my suggestion (bear with me as I treat all people as my university students) is to introduce the article by explaining a RESTSFull API is designed not by defining the procedures to call on a data element, but by defining a data element representation that has such and such attributes to allow such and such REST constrains.
                      >> Then go on saying that regular RPC approach would be to define that list of operations you have there. Next, explain that your first step would be to define the resource (entity and semantics), and then define a representation (a media type) that will help user-agents work with that resource. Make clear that the actual List (resource) is implemented in the server in whatever form the designer wants: it may be a table in a database, an in memory array, a Vector, even a HashTable of some sort, or a hierarchical filesystem structure, you imagine. Client does not care, it receives the representation/media type your are defining. That is because regular developer may thing the list SHOULD be stored in the server as an XML like the one you post, in other words, you are defining the actual storage format. Again, foresee confusion and be defensive.
                      >>
                      >> I wont go on with the rest of the article, but that would be my style. Long, slow description making special emphasis on some concepts that may be confusing to the reader. For instance, when mapping the protocol, be clear you are not mapping the operations in the beginning to those of the protocol (making the protocol your PRC implementor), but using the protocol semantics to manipulate the resource, getting similar results as the operations above, and stating that the actual manipulation may be different altogether.
                      >>
                      >> Of course, you have your style, and the approach of the article is great (show by doing), but our discussion about perceptions of the meaning of some concepts makes me carefully trying not to confuse the reader.
                      >>
                      >> Cheers!
                      >>
                      >> William Martinez.
                      >>
                      >>
                      >> --- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
                      >>>
                      >>> I've posted a blog entry labeled "A RESTful Hypermedia API in Three
                      >>> Easy Steps"[1]. I used Fielding's "REST APIs must be
                      >>> hypertext-driven"[2] as a reference.
                      >>>
                      >>> I'd appreciate all the feedback anyone would like to offer regarding
                      >>> the concepts, terminology, and implementation details described there.
                      >>>  If you prefer not to clutter this list, feel free to comment on the
                      >>> blog or email me directly. I also hang out in the #rest IRC channel on
                      >>> freednode if you'd like to carry on there.
                      >>>
                      >>> Thanks in advance.
                      >>>
                      >>> [1] http://amundsen.com/blog/archives/1041
                      >>> [2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
                      >>>
                      >>> mca
                      >>> http://amundsen.com/blog/
                      >>>
                      >>
                      >>
                      >>
                      >>
                      >> ------------------------------------
                      >>
                      >> Yahoo! Groups Links
                      >>
                      >>
                      >>
                      >>
                      >
                      >
                    Your message has been successfully submitted and would be delivered to recipients shortly.