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

Design questions for applying REST

Expand Messages
  • S. Mike Dierken
    I m defining a REST based interface to an internal system at work and wanted to clarify some design questions (especially around the use of PUT and the use of
    Message 1 of 13 , Jun 10, 2004
    • 0 Attachment
      I'm defining a REST based interface to an internal system at work and wanted to clarify some design questions (especially around the use of PUT and the use of 'synthesized' resources).
       
      I'm trying to model a system where multiple input documents (all XML) are used to generate a single final document. The submitted documents have their own identifiers (owned by the client) and the submitters do not know the identifier for the final document. The final document might or might not exist when a submission is received. I'm also trying to not use POST for everything.
       
      I could submit an input document:
      a) with POST to a generic resource and return the location of the final 'merged' document.
       - doing PUT or DELETE on the returned resource would nuke the 'merged' document. The input document would be stored, but would not have a URI. Seems like this approach is out.
       
      b) with POST to a generic resource and return the location of the stored input document.
       - this would allow the use of GET, PUT and DELETE on the stored input document for management, but the client would have to remember the server generated location and maintain a mapping. Somewhat annoying.
       - in order to get to the final merged document, the response would need to provide a reference to it. This means the representation has more information than what was submitted - another schema would be required (or a more flexible one).
       - I'm not concerned about the non-idempotent definition of POST, I can guarantee the server works in an idempotent manner (even if the client can't truly trust that across all services).
       
      c) with PUT to a specific resource
       - this would allow the use of GET, PUT and DELETE on the stored input document for management, and the client would not need to maintain a mapping of input document to stored input document. Sounds great so far.
       - in order to get to the final merged document, the response would need to provide a reference to it. This means the representation has more information than what was submitted - another schema would be required.
       - requests can be safely re-tried. Bonus.
       
      Question: if PUT were used, are the representations returned from the PUT and retrieved via GET supposed to be /exactly/ what was submitted in the PUT? This would make it difficult for the representation to have additional data to reference the other resource representing the 'merged' document.
       
      Question: if PUT were used, and the processing of the input 'adjusted' the content (like removing insignificant whitespace, or more drastically modifying actual text values) would this 'adjusting' break the requirements surrounding PUT?
       
      Question: the 'final' merged document has a URI, but it's use is read-only. How bad is it to have resources that do not support all methods?
       
      Question: what other issues are there when one resource is synthesized from updates to other resources?
       
       
    • John Belmonte
      ... I don t consider it that annoying that clients have to remember mappings. When you design so that state is not stored on the server, naturally it will
      Message 2 of 13 , Jun 11, 2004
      • 0 Attachment
        S. Mike Dierken wrote:
        > b) with POST to a generic resource and return the location of the stored
        > input document.
        > - this would allow the use of GET, PUT and DELETE on the stored input
        > document for management, but the client would have to remember the
        > server generated location and maintain a mapping. Somewhat annoying.
        > - in order to get to the final merged document, the response would need
        > to provide a reference to it. This means the representation has more
        > information than what was submitted - another schema would be required
        > (or a more flexible one).
        > - I'm not concerned about the non-idempotent definition of POST, I can
        > guarantee the server works in an idempotent manner (even if the client
        > can't truly trust that across all services).

        I don't consider it that annoying that clients have to remember
        mappings. When you design so that state is not stored on the server,
        naturally it will have to be stored elsewhere-- it's part of the
        client's job.

        In any case, you can make this plan more robust as follows: when the
        server creates a record for a new document, also store the digest of the
        request that caused it. Then, if it receives a duplicate request from
        the client, ignore it and return the exiting resource location.

        Also, assuming that input documents are not shared, the server could
        provide a query function that returns the output resource given an input
        resource URL.

        -John


        --
        http://giftfile.org/ :: giftfile project
      • S. Mike Dierken
        ... I have 40M+ resources, so I wasn t considering this as feasible. I also think that HTTP indicates that part of a server s job for handling PUT is for the
        Message 3 of 13 , Jun 11, 2004
        • 0 Attachment
          >
          > I don't consider it that annoying that clients have to remember
          > mappings. When you design so that state is not stored on the server,
          > naturally it will have to be stored elsewhere-- it's part of the
          > client's job.
          I have 40M+ resources, so I wasn't considering this as feasible.
          I also think that HTTP indicates that part of a server's job for handling
          PUT is for the client to be able to specify the URI.

          >
          > In any case, you can make this plan more robust as follows: when the
          > server creates a record for a new document, also store the digest of the
          > request that caused it. Then, if it receives a duplicate request from
          > the client, ignore it and return the exiting resource location.
          I'm not really worried about duplicate requests - the behavior would be to
          determine if the submitted content already had been submitted before. Either
          via the URI having the client-managed identifier or having the content
          contain the client-managed identifier.

          >
          > Also, assuming that input documents are not shared, the server could
          > provide a query function that returns the output resource given an input
          > resource URL.
          What would that look like? It'd be a compound URI, right? Whatever it would
          look like, I hadn't considered two resources - one for the stored input
          document and one with references to the synthesized output document, but in
          order to know about this second resource either the client generates that
          resource identifier or that identifer is contained in a representation of
          the stored input document - and I might as well point to the synthesized
          output document directly.
          Something to think about though, there's probably an answer in here
          somewhere....


          (Anyone else with some ideas/comments? Roy? Mark? Jeff? Paul? Rohit?)
        • Walden Mathews
          Why are you averse to using POST for all the operations that send data to the server? Walden ... From: S. Mike Dierken To: John
          Message 4 of 13 , Jun 12, 2004
          • 0 Attachment
            Why are you averse to using POST for all the operations
            that send data to the server?

            Walden

            ----- Original Message -----
            From: "S. Mike Dierken" <mdierken@...>
            To: "John Belmonte" <john@...>
            Cc: <rest-discuss@yahoogroups.com>
            Sent: Saturday, June 12, 2004 1:17 AM
            Subject: Re: [rest-discuss] Design questions for applying REST


            : >
            : > I don't consider it that annoying that clients have to remember
            : > mappings. When you design so that state is not stored on the server,
            : > naturally it will have to be stored elsewhere-- it's part of the
            : > client's job.
            : I have 40M+ resources, so I wasn't considering this as feasible.
            : I also think that HTTP indicates that part of a server's job for handling
            : PUT is for the client to be able to specify the URI.
            :
            : >
            : > In any case, you can make this plan more robust as follows: when the
            : > server creates a record for a new document, also store the digest of the
            : > request that caused it. Then, if it receives a duplicate request from
            : > the client, ignore it and return the exiting resource location.
            : I'm not really worried about duplicate requests - the behavior would be to
            : determine if the submitted content already had been submitted before.
            Either
            : via the URI having the client-managed identifier or having the content
            : contain the client-managed identifier.
            :
            : >
            : > Also, assuming that input documents are not shared, the server could
            : > provide a query function that returns the output resource given an input
            : > resource URL.
            : What would that look like? It'd be a compound URI, right? Whatever it
            would
            : look like, I hadn't considered two resources - one for the stored input
            : document and one with references to the synthesized output document, but
            in
            : order to know about this second resource either the client generates that
            : resource identifier or that identifer is contained in a representation of
            : the stored input document - and I might as well point to the synthesized
            : output document directly.
            : Something to think about though, there's probably an answer in here
            : somewhere....
            :
            :
            : (Anyone else with some ideas/comments? Roy? Mark? Jeff? Paul? Rohit?)
            :
            :
            :
            :
            : Yahoo! Groups Links
            :
            :
            :
            :
            :
            :
            :
            : __________ NOD32 1.786 (20040611) Information __________
            :
            : This message was checked by NOD32 antivirus system.
            : http://www.nod32.com
            :
            :
          • John Belmonte
            ... I wasn t suggesting you store all your resources on the client, so perhaps we misunderstand each other. I m not sure what your meaning is in that second
            Message 5 of 13 , Jun 12, 2004
            • 0 Attachment
              S. Mike Dierken wrote:
              >>I don't consider it that annoying that clients have to remember
              >>mappings. When you design so that state is not stored on the server,
              >>naturally it will have to be stored elsewhere-- it's part of the
              >>client's job.
              >
              > I have 40M+ resources, so I wasn't considering this as feasible.
              > I also think that HTTP indicates that part of a server's job for handling
              > PUT is for the client to be able to specify the URI.

              I wasn't suggesting you store all your resources on the client, so
              perhaps we misunderstand each other. I'm not sure what your meaning is
              in that second sentence.

              >>In any case, you can make this plan more robust as follows: when the
              >>server creates a record for a new document, also store the digest of the
              >>request that caused it. Then, if it receives a duplicate request from
              >>the client, ignore it and return the exiting resource location.
              >
              > I'm not really worried about duplicate requests - the behavior would be to
              > determine if the submitted content already had been submitted before. Either
              > via the URI having the client-managed identifier or having the content
              > contain the client-managed identifier.

              That's surprising to me. From your original post, case c:

              - requests can be safely re-tried. Bonus.

              From what I gathered, you hadn't considered that this could be covered
              in case b also.

              >>Also, assuming that input documents are not shared, the server could
              >>provide a query function that returns the output resource given an input
              >>resource URL.
              >
              > What would that look like? It'd be a compound URI, right? Whatever it would
              > look like, I hadn't considered two resources - one for the stored input
              > document and one with references to the synthesized output document, but in
              > order to know about this second resource either the client generates that
              > resource identifier or that identifer is contained in a representation of
              > the stored input document - and I might as well point to the synthesized
              > output document directly.

              I'm not sure where your concern comes from, as this is exactly what
              queries are for. For example:

              GET /myapp/outputs?input=/myapp/inputs/a98a6799 HTTP/1.1
              Host: example.net

              HTTP/1.1 302 Found
              Location: http://example.net/myapp/outputs/14f322410

              This is exactly the same as going to <http://example.net/myapp/outputs>,
              entering "/myapp/inputs/a98a6799" in the "input" field of a form, and
              being automatically redirected to
              <http://example.net/myapp/outputs/14f322410>.

              -John

              --
              http://giftfile.org/ :: giftfile project
            • S. Mike Dierken
              I d like to use PUT to update a resource in order to indicate to clients that the request is idempotent. The reliability/availability concerns here at work can
              Message 6 of 13 , Jun 12, 2004
              • 0 Attachment
                I'd like to use PUT to update a resource in order to indicate to clients
                that the request is idempotent.
                The reliability/availability concerns here at work can be addressed by
                repeating requests, but I'd like to be generally usable by taking advantage
                of the protocol definition, rather than just user-documentation that says
                it's okay.



                ----- Original Message -----
                From: "Walden Mathews" <walden@...>
                To: "S. Mike Dierken" <mdierken@...>
                Cc: <rest-discuss@yahoogroups.com>
                Sent: Saturday, June 12, 2004 5:13 AM
                Subject: Re: [rest-discuss] Design questions for applying REST


                > Why are you averse to using POST for all the operations
                > that send data to the server?
                >
                > Walden
                >
                > ----- Original Message -----
                > From: "S. Mike Dierken" <mdierken@...>
                > To: "John Belmonte" <john@...>
                > Cc: <rest-discuss@yahoogroups.com>
                > Sent: Saturday, June 12, 2004 1:17 AM
                > Subject: Re: [rest-discuss] Design questions for applying REST
                >
                >
                > : >
                > : > I don't consider it that annoying that clients have to remember
                > : > mappings. When you design so that state is not stored on the server,
                > : > naturally it will have to be stored elsewhere-- it's part of the
                > : > client's job.
                > : I have 40M+ resources, so I wasn't considering this as feasible.
                > : I also think that HTTP indicates that part of a server's job for
                handling
                > : PUT is for the client to be able to specify the URI.
                > :
                > : >
                > : > In any case, you can make this plan more robust as follows: when the
                > : > server creates a record for a new document, also store the digest of
                the
                > : > request that caused it. Then, if it receives a duplicate request from
                > : > the client, ignore it and return the exiting resource location.
                > : I'm not really worried about duplicate requests - the behavior would be
                to
                > : determine if the submitted content already had been submitted before.
                > Either
                > : via the URI having the client-managed identifier or having the content
                > : contain the client-managed identifier.
                > :
                > : >
                > : > Also, assuming that input documents are not shared, the server could
                > : > provide a query function that returns the output resource given an
                input
                > : > resource URL.
                > : What would that look like? It'd be a compound URI, right? Whatever it
                > would
                > : look like, I hadn't considered two resources - one for the stored input
                > : document and one with references to the synthesized output document, but
                > in
                > : order to know about this second resource either the client generates
                that
                > : resource identifier or that identifer is contained in a representation
                of
                > : the stored input document - and I might as well point to the synthesized
                > : output document directly.
                > : Something to think about though, there's probably an answer in here
                > : somewhere....
                > :
                > :
                > : (Anyone else with some ideas/comments? Roy? Mark? Jeff? Paul? Rohit?)
                > :
                > :
                > :
                > :
                > : Yahoo! Groups Links
                > :
                > :
                > :
                > :
                > :
                > :
                > :
                > : __________ NOD32 1.786 (20040611) Information __________
                > :
                > : This message was checked by NOD32 antivirus system.
                > : http://www.nod32.com
                > :
                > :
                >
                >
              • S. Mike Dierken
                ... handling ... I was just mentioning that it s a common pattern for a client to own the resource identifier and that HTTP supports this approach. It seems
                Message 7 of 13 , Jun 12, 2004
                • 0 Attachment
                  > > I also think that HTTP indicates that part of a server's job for
                  handling
                  > > PUT is for the client to be able to specify the URI.
                  >
                  > I'm not sure what your meaning is in that second sentence.
                  I was just mentioning that it's a common pattern for a client to 'own' the
                  resource identifier and that HTTP supports this approach. It seems to fit
                  well with my design problem.


                  >
                  > >>In any case, you can make this plan more robust as follows: when the
                  > >>server creates a record for a new document, also store the digest of the
                  > >>request that caused it. Then, if it receives a duplicate request from
                  > >>the client, ignore it and return the exiting resource location.
                  > >
                  > > I'm not really worried about duplicate requests - the behavior would be
                  to
                  > > determine if the submitted content already had been submitted before.
                  Either
                  > > via the URI having the client-managed identifier or having the content
                  > > contain the client-managed identifier.
                  >
                  > That's surprising to me. From your original post, case c:
                  >
                  > - requests can be safely re-tried. Bonus.
                  >
                  > From what I gathered, you hadn't considered that this could be covered in
                  case b also.
                  Sorry - I meant that I wasn't worried how it would be implemented. I know
                  that POST /might/ be implemented in an idempotent manner, but the bonus is
                  that PUT /requires/ it - a client does not need extra 'coordination'
                  (pre-arranged commitment from the service author) to re-try a request.


                  >
                  > >>Also, assuming that input documents are not shared, the server could
                  > >>provide a query function that returns the output resource given an input
                  > >>resource URL.
                  > >
                  > > What would that look like? It'd be a compound URI, right? Whatever it
                  would
                  > > look like, I hadn't considered two resources - one for the stored input
                  > > document and one with references to the synthesized output document, but
                  in
                  > > order to know about this second resource either the client generates
                  that
                  > > resource identifier or that identifer is contained in a representation
                  of
                  > > the stored input document - and I might as well point to the synthesized
                  > > output document directly.
                  >
                  > I'm not sure where your concern comes from, as this is exactly what
                  > queries are for. For example:
                  >
                  > GET /myapp/outputs?input=/myapp/inputs/a98a6799 HTTP/1.1
                  > Host: example.net
                  >
                  > HTTP/1.1 302 Found
                  > Location: http://example.net/myapp/outputs/14f322410
                  >
                  > This is exactly the same as going to <http://example.net/myapp/outputs>,
                  > entering "/myapp/inputs/a98a6799" in the "input" field of a form, and
                  > being automatically redirected to
                  > <http://example.net/myapp/outputs/14f322410>.
                  >
                  > -John
                  I think there is something good in this, but I still need to see how it
                  would work in my system - I have a feeling that there is a disconnect
                  somewhere in our discussion (probably me). (Also, using a URI in a query
                  term probably has text encoding issues, like if the first URI already has
                  query terms in it).

                  ==========
                  Using option b (POST-based)
                  In this use case, uri_0 is a service meta-description, uri_1 is the
                  'container' resource that accepts input documents, uri_2 is the newly
                  created input document, uri_3 is the resource that holds a mapping between
                  the input document and the 'merged' document and uri_4 is the final 'merged'
                  document.

                  --- request 1: create new input document, another 'merged' document is
                  updated from this input document as well ---
                  POST uri_1 HTTP/1.1
                  Content-type: text/xml
                  ...stuff...

                  HTTP/1.1 201 Created
                  Location: uri_2

                  --- request 2: get service meta-description (this is of course done earlier
                  & cached) ---
                  GET uri_0 HTTP/1.1
                  Accept: text/xml

                  HTTP/1.1 200 OK
                  Content-type: text/xml
                  ...description of how to generate resource identifiers...

                  (process service description to generate resource identifier - basically
                  uri_3 would have uri_2 (or something equivalent) in it.
                  I realize now what my mistake was - I assumed the client had enough
                  information to map to the final merged document - which isn't possible.)

                  --- request 3: use generated resource identifier of resource that provides
                  the mapping to final 'merged' document ---
                  GET uri_3 HTTP/1.1
                  Accept: text/xml

                  HTTP/1.1 303 See Other
                  Location: uri_4


                  (You might be able to avoid the mapping step by using PUT and having the
                  first request return the location of the 'merged' document in the Location
                  header. Not sure if that is acceptable or not.)
                • Walden Mathews
                  Mike, How about this: 1) POST input documents to a generic resource on the server that is responsible for associating these documents with their final merged
                  Message 8 of 13 , Jun 13, 2004
                  • 0 Attachment
                    Mike,

                    How about this:

                    1) POST input documents to a generic resource on the server
                    that is responsible for associating these documents with their final
                    merged counterpart, creating the latter when appropriate. You
                    can let this return the Location of the newly created input document
                    on the server, or not. In response to this POST, always return
                    the URI of the merged document, minimally.

                    2) design the merged document such that it contains, directly
                    or indirectly, an index to the input documents from which it has
                    been composed. In other words, there may be yet another resource
                    subordinate to each merged document whose only function is to
                    be an index of inputs. This is a list of URI at which the original
                    input documents are available verbatim for GET, PUT and DELETE.

                    3) Subsequent PUT or DELETE on the input doc URIs for a
                    given merge document have the expected verbatim effects on
                    those resources, plus some interesting side effects on the merge
                    document, but with the constraint that even those effects are
                    idempotent. That is, if the client decides to change the content of
                    /input1 via a PUT, the server incorporates that change into the
                    merged document in a consistent and idempotent manner.

                    Anything?

                    In the original, you said:

                    "The submitted documents have their own identifiers (owned by the client)"

                    Does this mean that they are already hosted elsewhere? If so are
                    you considering approaches in which they are not dually hosted
                    on your server?

                    Walden


                    ----- Original Message -----
                    From: "S. Mike Dierken" <mdierken@...>
                    To: "John Belmonte" <john@...>
                    Cc: <rest-discuss@yahoogroups.com>
                    Sent: Sunday, June 13, 2004 1:24 AM
                    Subject: Re: [rest-discuss] Design questions for applying REST


                    :
                    : > > I also think that HTTP indicates that part of a server's job for
                    : handling
                    : > > PUT is for the client to be able to specify the URI.
                    : >
                    : > I'm not sure what your meaning is in that second sentence.
                    : I was just mentioning that it's a common pattern for a client to 'own' the
                    : resource identifier and that HTTP supports this approach. It seems to fit
                    : well with my design problem.
                    :
                    :
                    : >
                    : > >>In any case, you can make this plan more robust as follows: when the
                    : > >>server creates a record for a new document, also store the digest of
                    the
                    : > >>request that caused it. Then, if it receives a duplicate request from
                    : > >>the client, ignore it and return the exiting resource location.
                    : > >
                    : > > I'm not really worried about duplicate requests - the behavior would
                    be
                    : to
                    : > > determine if the submitted content already had been submitted before.
                    : Either
                    : > > via the URI having the client-managed identifier or having the content
                    : > > contain the client-managed identifier.
                    : >
                    : > That's surprising to me. From your original post, case c:
                    : >
                    : > - requests can be safely re-tried. Bonus.
                    : >
                    : > From what I gathered, you hadn't considered that this could be covered
                    in
                    : case b also.
                    : Sorry - I meant that I wasn't worried how it would be implemented. I know
                    : that POST /might/ be implemented in an idempotent manner, but the bonus is
                    : that PUT /requires/ it - a client does not need extra 'coordination'
                    : (pre-arranged commitment from the service author) to re-try a request.
                    :
                    :
                    : >
                    : > >>Also, assuming that input documents are not shared, the server could
                    : > >>provide a query function that returns the output resource given an
                    input
                    : > >>resource URL.
                    : > >
                    : > > What would that look like? It'd be a compound URI, right? Whatever it
                    : would
                    : > > look like, I hadn't considered two resources - one for the stored
                    input
                    : > > document and one with references to the synthesized output document,
                    but
                    : in
                    : > > order to know about this second resource either the client generates
                    : that
                    : > > resource identifier or that identifer is contained in a representation
                    : of
                    : > > the stored input document - and I might as well point to the
                    synthesized
                    : > > output document directly.
                    : >
                    : > I'm not sure where your concern comes from, as this is exactly what
                    : > queries are for. For example:
                    : >
                    : > GET /myapp/outputs?input=/myapp/inputs/a98a6799 HTTP/1.1
                    : > Host: example.net
                    : >
                    : > HTTP/1.1 302 Found
                    : > Location: http://example.net/myapp/outputs/14f322410
                    : >
                    : > This is exactly the same as going to <http://example.net/myapp/outputs>,
                    : > entering "/myapp/inputs/a98a6799" in the "input" field of a form, and
                    : > being automatically redirected to
                    : > <http://example.net/myapp/outputs/14f322410>.
                    : >
                    : > -John
                    : I think there is something good in this, but I still need to see how it
                    : would work in my system - I have a feeling that there is a disconnect
                    : somewhere in our discussion (probably me). (Also, using a URI in a query
                    : term probably has text encoding issues, like if the first URI already has
                    : query terms in it).
                    :
                    : ==========
                    : Using option b (POST-based)
                    : In this use case, uri_0 is a service meta-description, uri_1 is the
                    : 'container' resource that accepts input documents, uri_2 is the newly
                    : created input document, uri_3 is the resource that holds a mapping between
                    : the input document and the 'merged' document and uri_4 is the final
                    'merged'
                    : document.
                    :
                    : --- request 1: create new input document, another 'merged' document is
                    : updated from this input document as well ---
                    : POST uri_1 HTTP/1.1
                    : Content-type: text/xml
                    : ...stuff...
                    :
                    : HTTP/1.1 201 Created
                    : Location: uri_2
                    :
                    : --- request 2: get service meta-description (this is of course done
                    earlier
                    : & cached) ---
                    : GET uri_0 HTTP/1.1
                    : Accept: text/xml
                    :
                    : HTTP/1.1 200 OK
                    : Content-type: text/xml
                    : ...description of how to generate resource identifiers...
                    :
                    : (process service description to generate resource identifier - basically
                    : uri_3 would have uri_2 (or something equivalent) in it.
                    : I realize now what my mistake was - I assumed the client had enough
                    : information to map to the final merged document - which isn't possible.)
                    :
                    : --- request 3: use generated resource identifier of resource that provides
                    : the mapping to final 'merged' document ---
                    : GET uri_3 HTTP/1.1
                    : Accept: text/xml
                    :
                    : HTTP/1.1 303 See Other
                    : Location: uri_4
                    :
                    :
                    : (You might be able to avoid the mapping step by using PUT and having the
                    : first request return the location of the 'merged' document in the Location
                    : header. Not sure if that is acceptable or not.)
                    :
                    :
                    :
                    :
                    : Yahoo! Groups Links
                    :
                    :
                    :
                    :
                    :
                    :
                    :
                    : __________ NOD32 1.787 (20040612) Information __________
                    :
                    : This message was checked by NOD32 antivirus system.
                    : http://www.nod32.com
                    :
                    :
                  • S. Mike Dierken
                    ... Thanks Walden, I think this is a great REST pattern (described by others as well - I wonder if we should start a design patterns page for REST on the
                    Message 9 of 13 , Jun 13, 2004
                    • 0 Attachment
                      > 1) POST input documents to a generic resource on the server
                      > that is responsible for associating these documents with their final
                      > merged counterpart, creating the latter when appropriate. You
                      > can let this return the Location of the newly created input document
                      > on the server, or not. In response to this POST, always return
                      > the URI of the merged document, minimally.
                      Thanks Walden, I think this is a great REST pattern (described by others as
                      well - I wonder if we should start a 'design patterns' page for REST on the
                      Wiki).
                      I'm curious about the comparison of this approach to using PUT directly to
                      create/update input documents. From my understanding, the biggest difference
                      is whether the client constructs a URI to the input document, or the server
                      provides an opaque identifer and the client maintains a mapping between
                      submitted content and a server hosted resource.


                      >
                      > 2) design the merged document such that it contains, directly
                      > or indirectly, an index to the input documents from which it has
                      > been composed. In other words, there may be yet another resource
                      > subordinate to each merged document whose only function is to
                      > be an index of inputs. This is a list of URI at which the original
                      > input documents are available verbatim for GET, PUT and DELETE.
                      Definitely possible, but I don't see the utility for the use cases I intend
                      to support. (I'm putting a REST layer on top of an existing, critical
                      business function - this capability doesn't map to the existing uses of the
                      system).

                      >
                      > 3) Subsequent PUT or DELETE on the input doc URIs for a
                      > given merge document have the expected verbatim effects on
                      > those resources, plus some interesting side effects on the merge
                      > document, but with the constraint that even those effects are
                      > idempotent. That is, if the client decides to change the content of
                      > /input1 via a PUT, the server incorporates that change into the
                      > merged document in a consistent and idempotent manner.
                      Yes, perfect. That's what I'm shooting for. The question is, can the client
                      do a PUT directly, without passing through the generic resource described in
                      step 1? What are the specific tradeoffs?

                      > In the original, you said:
                      >
                      > "The submitted documents have their own identifiers (owned by the client)"
                      >
                      > Does this mean that they are already hosted elsewhere? If so are
                      > you considering approaches in which they are not dually hosted
                      > on your server?
                      The client-owned identifiers are not URIs nor do the indicate retrievable
                      resources. If I squint, the current system looks more like a message-queue
                      system than a resource-based system, so there is almost no incoming data
                      that is 'globally' addressable/retrievable.

                      These client-owned identifiers are something I am thinking are important to
                      expose in URIs. These identifiers are going to be scattered across multiple
                      systems (internal and external) and the simplest integration seems to be for
                      the service to support requests that are composed mainly of this
                      client-owned identifier. Which is why I'm so interested in using PUT
                      directly rather than the generic resource that accept submissions (that
                      approach seems too 'message' oriented and not 'resource' oriented).

                      Thanks for all the discussion folks!
                    • Walden Mathews
                      ... From: S. Mike Dierken To: Walden Mathews Cc: Sent: Monday, June 14, 2004
                      Message 10 of 13 , Jun 14, 2004
                      • 0 Attachment
                        ----- Original Message -----
                        From: "S. Mike Dierken" <mdierken@...>
                        To: "Walden Mathews" <walden@...>
                        Cc: <rest-discuss@yahoogroups.com>
                        Sent: Monday, June 14, 2004 12:49 AM
                        Subject: Re: [rest-discuss] Design questions for applying REST


                        | > 1) POST input documents to a generic resource on the server
                        | > that is responsible for associating these documents with their final
                        | > merged counterpart, creating the latter when appropriate. You
                        | > can let this return the Location of the newly created input document
                        | > on the server, or not. In response to this POST, always return
                        | > the URI of the merged document, minimally.
                        | Thanks Walden, I think this is a great REST pattern (described by others
                        as
                        | well - I wonder if we should start a 'design patterns' page for REST on
                        the
                        | Wiki).

                        Same old REST stuff, agreed.

                        | I'm curious about the comparison of this approach to using PUT directly
                        to
                        | create/update input documents. From my understanding, the biggest
                        difference
                        | is whether the client constructs a URI to the input document, or the
                        server
                        | provides an opaque identifer and the client maintains a mapping between
                        | submitted content and a server hosted resource.

                        I'm curious about your curiosity. You're the guy who knows
                        the application's constraints, such as whether the client is willing
                        to maintain a mapping. Since (from below) the source doc ids
                        are not URI, doesn't the client have to maintain a mapping either
                        way?

                        |
                        |
                        | >
                        | > 2) design the merged document such that it contains, directly
                        | > or indirectly, an index to the input documents from which it has
                        | > been composed. In other words, there may be yet another resource
                        | > subordinate to each merged document whose only function is to
                        | > be an index of inputs. This is a list of URI at which the original
                        | > input documents are available verbatim for GET, PUT and DELETE.
                        | Definitely possible, but I don't see the utility for the use cases I
                        intend
                        | to support. (I'm putting a REST layer on top of an existing, critical
                        | business function - this capability doesn't map to the existing uses of
                        the
                        | system).

                        Wow. I thought this would be the key, since in previous discussion
                        you were talking about algorithms and meta-specifications to tell the
                        client how to construct a merge URI from a source URI or vice versa,
                        (or something like that). In my mind, the identity of the input documents
                        logically belongs as a sub-resource to the merged content resources,
                        just as a bibliography exists in relation to a research paper. This
                        would relieve the client from having to maintain those relationships
                        in its own space, if it doesn't want to. And I thought that was also
                        a key goal in your design...


                        |
                        | >
                        | > 3) Subsequent PUT or DELETE on the input doc URIs for a
                        | > given merge document have the expected verbatim effects on
                        | > those resources, plus some interesting side effects on the merge
                        | > document, but with the constraint that even those effects are
                        | > idempotent. That is, if the client decides to change the content of
                        | > /input1 via a PUT, the server incorporates that change into the
                        | > merged document in a consistent and idempotent manner.
                        | Yes, perfect. That's what I'm shooting for. The question is, can the
                        client
                        | do a PUT directly, without passing through the generic resource described
                        in
                        | step 1? What are the specific tradeoffs?

                        If a merged document contains a set of references to the input
                        documents on which it is based, and the client is able to retrieve
                        those as URI, then why couldn't the client do a PUT directly to
                        one? What sort of tradeoffs are you interested in?

                        To me, the interesting part of this is that doing a PUT to an input
                        document URI has a side effect on the merge document. I don't
                        know of a REST constraint (or HTTP constraint) that this violates.
                        Anyone?

                        |
                        | > In the original, you said:
                        | >
                        | > "The submitted documents have their own identifiers (owned by the
                        client)"
                        | >
                        | > Does this mean that they are already hosted elsewhere? If so are
                        | > you considering approaches in which they are not dually hosted
                        | > on your server?
                        | The client-owned identifiers are not URIs nor do the indicate retrievable
                        | resources. If I squint, the current system looks more like a message-queue
                        | system than a resource-based system, so there is almost no incoming data
                        | that is 'globally' addressable/retrievable.
                        |
                        | These client-owned identifiers are something I am thinking are important
                        to
                        | expose in URIs. These identifiers are going to be scattered across
                        multiple
                        | systems (internal and external)

                        what does that mean?

                        | and the simplest integration seems to be for
                        | the service to support requests that are composed mainly of this
                        | client-owned identifier.

                        It seems to me that either your client is constrained to accessing
                        these objects through an identification scheme that is already
                        implemented, or it isn't, and there is no real middle ground.

                        If you're taking a legacy application and putting it "on the Web",
                        then your clients are going to have to accept a face lift, no?


                        |Which is why I'm so interested in using PUT
                        | directly rather than the generic resource that accept submissions (that
                        | approach seems too 'message' oriented and not 'resource' oriented).

                        In terms of REST, I think those resources aren't Web resources
                        until they don Web identifiers. The tradeoff I see is in the impact
                        on your client. By sending a message, you can keep your client out
                        of the URI manufacturing business. Otherwise, I don't see the
                        conflict between message orientation and resource orientation.

                        Walden
                      • Tony Butterfield
                        ... and wanted to clarify some design questions (especially around the use of PUT and the use of synthesized resources). ... XML) are used to generate a
                        Message 11 of 13 , Jun 14, 2004
                        • 0 Attachment
                          --- In rest-discuss@yahoogroups.com, "S. Mike Dierken" <mdierken@h...>
                          wrote:
                          > I'm defining a REST based interface to an internal system at work
                          and wanted to clarify some design questions (especially around the use
                          of PUT and the use of 'synthesized' resources).
                          >
                          > I'm trying to model a system where multiple input documents (all
                          XML) are used to generate a single final document. The submitted
                          documents have their own identifiers (owned by the client) and the
                          submitters do not know the identifier for the final document. The
                          final document might or might not exist when a submission is received.
                          I'm also trying to not use POST for everything.
                          >
                          I was wondering what your reasons are for not considering a service
                          based approach where the client constructs a request containing all
                          the input documents and the response is the merged document?

                          I don't think this violates the principles of REST and it simplifies
                          things quite a bit.

                          The practicalities would be that your client could construct a
                          multipart body containing all the input document and POST it to your
                          service URI. The service could then process the request and return a
                          non-cacheable response with the merged document as the body.

                          Cheers,
                          Tony
                        • S. Mike Dierken
                          ... to ... difference ... server ... In my environment, I doubt the clients would maintain a mapping. ... I m thinking that if the URI is constructed only from
                          Message 12 of 13 , Jun 14, 2004
                          • 0 Attachment
                            >
                            > | I'm curious about the comparison of this approach to using PUT directly
                            to
                            > | create/update input documents. From my understanding, the biggest
                            difference
                            > | is whether the client constructs a URI to the input document, or the
                            server
                            > | provides an opaque identifer and the client maintains a mapping between
                            > | submitted content and a server hosted resource.
                            >
                            > I'm curious about your curiosity. You're the guy who knows
                            > the application's constraints, such as whether the client is willing
                            > to maintain a mapping.
                            In my environment, I doubt the clients would maintain a mapping.

                            > Since (from below) the source doc ids
                            > are not URI, doesn't the client have to maintain a mapping either way?
                            I'm thinking that if the URI is constructed only from static elements and
                            the source doc IDs, then the mapping is purely algorithmic.

                            > | > 2) design the merged document such that it contains, directly
                            > | > or indirectly, an index to the input documents from which it has
                            > | > been composed. In other words, there may be yet another resource
                            > | > subordinate to each merged document whose only function is to
                            > | > be an index of inputs. This is a list of URI at which the original
                            > | > input documents are available verbatim for GET, PUT and DELETE.
                            > | Definitely possible, but I don't see the utility for the use cases I
                            intend
                            > | to support. (I'm putting a REST layer on top of an existing, critical
                            > | business function - this capability doesn't map to the existing uses of
                            the
                            > | system).
                            >
                            > Wow. I thought this would be the key, since in previous discussion
                            > you were talking about algorithms and meta-specifications to tell the
                            > client how to construct a merge URI from a source URI or vice versa,
                            > (or something like that).
                            I probably mis-communicated something - I don't think in my case I can use a
                            meta-specification to construct the merged document URI from a source ID. I
                            can use a meta-specification to construct the URI of an input document from
                            the client-owned document ID, but this implies the server uses the
                            client-owned ID in the URI rather than some internal identifier. I don't
                            have a problem with that & I actually think this approach makes initial
                            integration easier in general.


                            > In my mind, the identity of the input documents
                            > logically belongs as a sub-resource to the merged content resources,
                            > just as a bibliography exists in relation to a research paper.
                            I'm not sure what a 'sub-resource' is. The merged content could have
                            references sure, but in my situation I typically do not want to expose the
                            input documents that were used to generate the merged output document
                            (although if my REST service were internal to the company, that wouldn't be
                            a big deal).

                            > This would relieve the client from having to maintain those relationships
                            > in its own space, if it doesn't want to. And I thought that was also
                            > a key goal in your design...
                            I think the approach I'll be taking is for the server to use the
                            client-owned document ID in the URI of the input document, which allows a
                            client to use PUT directly without needing a generic resource that accepted
                            POST (although this could be supported as a convenience). Then I'd have a
                            resource that maps input documents to merged documents & the URI for the
                            mapping resource could be constructed purely from client-owned document ID.

                            >
                            > |
                            > | >
                            > | > 3) Subsequent PUT or DELETE on the input doc URIs for a
                            > | > given merge document have the expected verbatim effects on
                            > | > those resources, plus some interesting side effects on the merge
                            > | > document, but with the constraint that even those effects are
                            > | > idempotent. That is, if the client decides to change the content of
                            > | > /input1 via a PUT, the server incorporates that change into the
                            > | > merged document in a consistent and idempotent manner.
                            > | Yes, perfect. That's what I'm shooting for. The question is, can the
                            client
                            > | do a PUT directly, without passing through the generic resource
                            described in
                            > | step 1? What are the specific tradeoffs?
                            >
                            > If a merged document contains a set of references to the input
                            > documents on which it is based, and the client is able to retrieve
                            > those as URI, then why couldn't the client do a PUT directly to
                            > one? What sort of tradeoffs are you interested in?
                            How would it know which input document resource to PUT to?


                            >
                            > To me, the interesting part of this is that doing a PUT to an input
                            > document URI has a side effect on the merge document. I don't
                            > know of a REST constraint (or HTTP constraint) that this violates.
                            Yes - this is the core design pattern for REST that I would like to explore.
                            I'm going to build it one way or the other, just looking for advice.

                            > Anyone?

                            > | These client-owned identifiers are something I am thinking are important
                            to
                            > | expose in URIs. These identifiers are going to be scattered across
                            multiple
                            > | systems (internal and external)
                            >
                            > what does that mean?
                            These document IDs are stored as a column in a database by other groups
                            within the company (not as a URI). I'd like to be able to provide a simple
                            client library (or documentation) which helps these other groups access my
                            system which stores the input documents and the merged output document. I'm
                            looking for something with the most bang for the buck and the least number
                            of objections ("what? another network request? Performance would suck! Who
                            are you and where did you come from?!?")

                            >
                            > | and the simplest integration seems to be for
                            > | the service to support requests that are composed mainly of this
                            > | client-owned identifier.
                            >
                            > It seems to me that either your client is constrained to accessing
                            > these objects through an identification scheme that is already
                            > implemented, or it isn't, and there is no real middle ground.
                            I think the clients are willing to use URIs but not necessarily to retrieve
                            a mapping from their IDs to the server's IDs.

                            >
                            > If you're taking a legacy application and putting it "on the Web",
                            > then your clients are going to have to accept a face lift, no?
                            I'd like to establish that the use of URIs (to make existing resources
                            actually truly addressable) has value. After that I can get into location
                            independence via a request to a 'mapping resource'. I might also be able to
                            move toward exposing these resources on the public Web (but I'd need a layer
                            in-between to map internal IDs to secure public-facing IDs).


                            > By sending a message, you can keep your client out
                            > of the URI manufacturing business.
                            Not sure I understand. The only request I see that avoids constructing a URI
                            is via the generic resource that accepts input document submissions and
                            returns the URI for direct access.

                            > Otherwise, I don't see the conflict between message orientation and
                            resource orientation.
                            For me, the message orientation lacks URIs for stored documents (input
                            documents and merged documents).

                            Thanks!
                          • S. Mike Dierken
                            ... The clients in this case don t have all the inputs. The service they submit data to is the storage service. ... If the service were purely an algorithm,
                            Message 13 of 13 , Jun 15, 2004
                            • 0 Attachment
                              > I was wondering what your reasons are for not considering a service
                              > based approach where the client constructs a request containing all
                              > the input documents and the response is the merged document?
                              The clients in this case don't have all the inputs. The service they submit
                              data to is the storage service.

                              >
                              > I don't think this violates the principles of REST and it simplifies
                              > things quite a bit.
                              >
                              > The practicalities would be that your client could construct a
                              > multipart body containing all the input document and POST it to your
                              > service URI. The service could then process the request and return a
                              > non-cacheable response with the merged document as the body.
                              If the service were purely an algorithm, yes I could do this. But I'm going
                              for persistence.
                            Your message has been successfully submitted and would be delivered to recipients shortly.