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

Re: [rest-discuss] Hypermedia controls

Expand Messages
  • Jan Algermissen
    ... Yes, it does in a numner of areas - and wrongly so. AtomPub creates the impression that the client can makes certain assumptions (but it actually musn t).
    Message 1 of 27 , Mar 23, 2010
      On Mar 23, 2010, at 4:38 PM, Ian Robinson wrote:

      >
      >
      > On 23 March 2010 14:05, Jan Algermissen <algermissen1971@...> wrote:
      >
      > (an operation name in a relation name is confusing matters. Note that 'edit' in AtomPub does not mean 'PUT here to edit' it means 'here is the authorable resource'). If you can afford the round trip, you would not even need that because a redirected PUT on the member resource would do the trick.
      >
      > Sorry, but I disagree with this Jan. AtomPub specifies which HTTP idioms to use to manipulate a resource. It constrains HTTP.

      Yes, it does in a numner of areas - and wrongly so. AtomPub creates the impression that the client can makes certain assumptions (but it actually musn't). For example, AtomPub also errs by prescribing the representation type (Atom feed) to return for a GET on a collection.

      > Sure, the specification of which method to use is not part of the "edit" definition - you're correct there - but AtomPub explicitly associates PUT with updates to a member URI (as indicated by an "edit" link). HTTP doesn't tell me how to delete or update members, just as it doesn't tell me how to delete or update contact info.

      Yes it does: it gives you PUT and DELETE. AtomPubs treatment of these 'editing patterns' is just overspecification that leads to clients with unRESTful built-ion assumptions.

      > AtomPub, however, tells me how to delete and update members. Please don't overload HTTP method definitions with some domain-specific operation semantics.

      I do not see any overloading going on: PUT means 'store the entity at the specified resource' and DELETE means 'delete any representations of the specified resource' there is nothing more to it really.

      >
      > (And whilst in this case it's the AtomPub spec that glues together an HTTP idiom and a link relation value in the context of a specific application goal, I see no reason why more specialized link relation definitions can't take it upon themselves to make this association.

      Yes it can - it is just not necessary. If I know that a resource is a 'contact info resource' then PUT simply means update that contact info. The situation is different with POST, where you might want to say that posting to the order-processor resource has the domain semantics of 'placing an order'.

      > It all depends on how "general" you want the link relation to be. I think Subbu's talked about this a bit before).
      >
      > It's unfortunate that you've chosen "edit" over "updateContactInfo", because taken all by itself, "edit" looks just like a verb...

      Yes, 'source' would probably have been a better name for the link rel.

      > Of course, it could be a substantive, much as "update" can be. The definition of edit, however, makes it clear that this isn't an operation definition. Just as the definition of "updateContactInfo" might.

      Ok, but I am pretty sure that this was not the original intention. I much too often see

      updateContactInfo
      deleteContactInfo

      when people should just use

      contactInfo and get the PUT and DELETE for free.

      >
      > The real concern I have here is the attempt to find nouns and verbs in URIs. Someone took a wrong turn quite some time ago on this, and we all seem to be suffering with its legacy.

      Right - that is why action-like URIs bother me so much. Even more so when POST comes into play as in

      POST /order/pay

      [empty body]

      which is unREStful because the message is not self descriptive but depends on the current server side state of /order.

      That should really be:

      POST /payment-processor

      <order>
      ..
      </order>


      Jan






      >
      > Kind regards
      >
      > ian
      >

      -----------------------------------
      Jan Algermissen, Consultant
      NORD Software Consulting

      Mail: algermissen@...
      Blog: http://www.nordsc.com/blog/
      Work: http://www.nordsc.com/
      -----------------------------------
    • Kevin Duffey
      Hi all, ... I don t agree with this personally. How do I know that I can call PUT, DELETE, GET or POST on that one url? By this I mean.. why should a client
      Message 2 of 27 , Mar 23, 2010
        Hi all,


        >Ok, but I am pretty sure that this was not the original intention. I much too often see
        >
        >updateContactInfo
        >deleteContactInfo
        >
        >when people should just use
        >
        >contactInfo and get the PUT and DELETE for free.

        I don't agree with this personally. How do I know that I can call PUT, DELETE, GET or POST on that one url? By this I mean.. why should a client waste another round trip hoping something works, when it might not. I much prefer something like:

        <link rel="edit" href="..." type="..." methods="get,delete"/>

        I don't see why this is bad... it allows a client to still discover the URL to call, but also provides the specific methods it can call on that URL at that time. It saves the client from making a request that will result in a method not allowed or some other error response. It also saves the server side from inundated requests that are going to respond with errors that could quite easily be avoided by simply providing the methods allowed on the resource in the first place.

        Is there perhaps a better way to do what I've said above?

        As well, if I return a response with several links, how do I specify in those the media types to use? For example, if the URL that was called is /orders and the media type is application/vnd.org.company.orders+xml, then I know that if the response comes back with links with /orders in it, I can use the same media type. But what if I return other links too, that allow a user to pull up history, using a history resource, and some other things. Where do I specify the media type? Does the user discover this URL (link), then make an OPTIONS call to it to get the media type it should use for that resource?

        My thought is something like

        GET /orders

        <links>
          <link rel="self" href="../orders"/>
          <link rel="edit" href="../orders"/>
          <link rel="history" href=".../history" type="application/vnd.org.company.history+xml"/>
        </links>

        Perhaps we provide methods="..." in the history link as well, allowing the client to not only discover it, but know what methods can be performed on that url at that time.



      • Eric J. Bowman
        ... (...) ... Yes, particularly since there s no such thing as @methods... What you can do, in response to any request method invoked on a resource, is send
        Message 3 of 27 , Mar 23, 2010
          Kevin Duffey wrote:
          >
          > <link rel="edit" href="..." type="..." methods="get,delete"/>
          >
          (...)
          >
          > Is there perhaps a better way to do what I've said above?
          >

          Yes, particularly since there's no such thing as @methods... What you
          can do, in response to any request method invoked on a resource, is
          send "Allow: HEAD, GET, DELETE" (don't forget HEAD) and Accept headers.

          The 'edit' link relation is commonly understood to support GET, PUT and
          DELETE. If your application isn't accepting PUT, then respond 405 or
          501 as appropriate, along with the Allow: header. If PUT is accepted,
          but the wrong media type is used, respond 415 -- what's authoritative
          in REST is the response code for any given request, i.e. the only way
          to know if DELETE is actually allowed, is if a DELETE request yields a
          2xx response.

          You don't have to specify all this implementation detail in your markup.
          Including it in headers still qualifies as "hypertext" so don't sweat
          it. The Accept and Allow headers are part of implementing the self-
          descriptive messaging constraint, and the hypertext constraint.

          Of course, the Allow and Accept headers can't tell you what media type
          to associate with what method. Although in this case, it's implied by
          the media type definitions themselves to some extent:

          Accept: application/atom+xml, application/x-www-urlencoded
          Allow: HEAD, GET, PUT, POST, DELETE
          Content-Type: application/atom+xml

          I wouldn't expect to be able to PUT application/x-www-urlencoded. But
          headers aren't fine-grained enough to express whether I can POST
          application/atom+xml. The rest of the hypertext constraint is met via
          markup, which is fine-grained enough to express a self-documenting API.

          But, this isn't done with <link/>, it's done with <form>, either Xforms
          or HTML 5 allow you to read the href of a <link rel='edit'/> (or rel=
          'source') and express not only _that_ it may have its GET or DELETE
          method called, but _how_ to call those methods, i.e. user dereferences a
          link or clicks a 'delete' button.

          -Eric
        • Mark Baker
          ... Because it s an URL. ... If you re looking for guarantees, stick to a LAN. But even then... does including delete in @methods, and making that page
          Message 4 of 27 , Mar 23, 2010
            On Tue, Mar 23, 2010 at 11:45 PM, Kevin Duffey <andjarnic@...> wrote:
            > I don't agree with this personally. How do I know that I can call PUT, DELETE, GET or POST on that one url?

            Because it's an URL.

            > By this I mean.. why should a client waste another round trip hoping something works, when it might not.

            If you're looking for guarantees, stick to a LAN. But even then...
            does including "delete" in @methods, and making that page cacheable
            for a day mean that all DELETE operations on that URL for the next day
            will never return anything other than 2xx? Of course not. Stuff
            changes, and you need to start writing code that can deal with that.

            WADL anyone?

            Mark.
          • Kevin Duffey
            Hola, ... So then, I am forced to make multiple requests to figure out what I can do? Because it s a URL, I hope that a PUT works.. and if it doesn t, I ve
            Message 5 of 27 , Mar 23, 2010
              Hola,



              >> I don't agree with this personally. How do I know that I can call PUT, DELETE, GET >>or POST on that one url?

              >Because it's an URL.

              So then, I am forced to make multiple requests to figure out what I can do? Because it's a URL, I hope that a PUT works.. and if it doesn't, I've wasted a round trip to be told it doesn't accept a PUT? That seems really ass backwards to me to be honest. Maybe it's the right way, but it sure seems silly that we have the capability to return a response that includes enough info in it to save the client side (and server side) from wasted round trips just because that's the way it's supposed to be.


              >> By this I mean.. why should a client waste another
              round trip hoping something >>works, when it might not.

              >If you're looking for guarantees, stick to a LAN.  But even then...
              >does including "delete" in @methods, and making that page cacheable
              >for a day mean that all DELETE operations on that URL for the next day
              >will never return anything other than 2xx?  Of course not.  Stuff
              >changes, and you need to start writing code that can deal with that.

              Agreed.. and plan to.. but why not help reduce network load, server load, and wasting client time when we can provide the info that does all that? I guess I am failing to understand who made up these rules that a client can just assume all HTTP methods will work... and oops.. if only we had been given a wee bit more info that a PUT was not acceptable on this URL before we made that call and got slapped on the wrist. It seems silly to me that this is the way it must work or it's not REST. Or maybe I am misunderstanding something... but it sounds like Mark, you are saying, too bad, deal with it, code for it, that's the way it works. Period.

            • Jan Algermissen
              ... Ask yourself *why* you PUT in the first place. Surely not just to see if something happens - the media types involved will tell you the semantics of link
              Message 6 of 27 , Mar 24, 2010
                On Mar 24, 2010, at 6:17 AM, Kevin Duffey wrote:

                >
                >
                > Hola,
                >
                >
                >
                > >> I don't agree with this personally. How do I know that I can call PUT, DELETE, GET >>or POST on that one url?
                >
                > >Because it's an URL.
                >
                > So then, I am forced to make multiple requests to figure out what I can do? Because it's a URL, I hope that a PUT works.. and if it doesn't, I've wasted a round trip to be told it doesn't accept a PUT? That seems really ass backwards to me to be honest.

                Ask yourself *why* you PUT in the first place. Surely not just to see if something happens - the media types involved will tell you the semantics of link targets (e.g. "this is contact info"). If your intention is to update contact info PUT is the natural thing to do because the HTTP spec tells you so. What other method would you use to update the contact info? DELETE? It makes no sense to specifiy the supported methods because they are not interchangeable.

                (HTML forms just do that because they are a single hypermedia control for two entirely different kinds of operations (indexing vs. data submission). Better would probably have been some kind of <indexable href=""><input ...></indexable> and <dataSink href=""><input.../></dataSink>.

                Instead of trying to read some fancy mechanisms into the hypermedia constraint, focus on proper media type design instead - that is hard enough already...


                > Maybe it's the right way, but it sure seems silly that we have the capability to return a response that includes enough info in it to save the client side (and server side) from wasted round trips just because that's the way it's supposed to be.

                Maybe it helps if you sketch some interactions where you think you would need some @methods?



                >
                >
                > >> By this I mean.. why should a client waste another round trip hoping something >>works, when it might not.
                >
                > >If you're looking for guarantees, stick to a LAN. But even then...
                > >does including "delete" in @methods, and making that page cacheable
                > >for a day mean that all DELETE operations on that URL for the next day
                > >will never return anything other than 2xx? Of course not. Stuff
                > >changes, and you need to start writing code that can deal with that.
                >
                > Agreed.. and plan to.. but why not help reduce network load, server load, and wasting client time when we can provide the info that does all that?

                Does *what*? Suppose you try to PUT and the server tells you that PUT is not supported? Do you think you would change the method and retry the request? What the server is really telling you is that your assumptions are broken and changing the method will not help that.


                > I guess I am failing to understand who made up these rules that a client can just assume all HTTP methods will work... and oops.. if only we had been given a wee bit more info that a PUT was not acceptable on this URL before we made that call and got slapped on the wrist.

                Hey - do you PUT to a resource because there is some information that tells you that the resourece accets PUT? Or do you also use other information about the resource?

                Jan


                > It seems silly to me that this is the way it must work or it's not REST. Or maybe I am misunderstanding something... but it sounds like Mark, you are saying, too bad, deal with it, code for it, that's the way it works. Period.
                >
                >
                >
                >

                -----------------------------------
                Jan Algermissen, Consultant
                NORD Software Consulting

                Mail: algermissen@...
                Blog: http://www.nordsc.com/blog/
                Work: http://www.nordsc.com/
                -----------------------------------
              • António Mota
                2010/3/24 Jan Algermissen ... But that is what HTTP says, not what REST says. REST mandates a Uniform Interface, not *the* uniform
                Message 7 of 27 , Mar 24, 2010
                  2010/3/24 Jan Algermissen <algermissen1971@...>
                   


                  On Mar 24, 2010, at 6:17 AM, Kevin Duffey wrote:

                  >
                  >
                  > Hola,
                  >
                  >
                  >
                  > >> I don't agree with this personally. How do I know that I can call PUT, DELETE, GET >>or POST on that one url?
                  >
                  > >Because it's an URL.
                  >
                  > So then, I am forced to make multiple requests to figure out what I can do? Because it's a URL, I hope that a PUT works.. and if it doesn't, I've wasted a round trip to be told it doesn't accept a PUT? That seems really ass backwards to me to be honest.

                  Ask yourself *why* you PUT in the first place. Surely not just to see if something happens - the media types involved will tell you the semantics of link targets (e.g. "this is contact info"). If your intention is to update contact info PUT is the natural thing to do because the HTTP spec tells you so. What other method would you use to update the contact info?

                  But that is what HTTP says, not what REST says. REST mandates a Uniform Interface, not *the* uniform interface GET/PUT/POST/DELETE.

                  There's nothing unrestfull if I decide to create a REST-based architecture with a Uniform Interface compose of XPTA, XPTB, XPTC and XPTD... How, then, you know what is "natural" or not? How, then, do you "formally" associate a media-type with this methods, in terms of semantics?

                  You know what I mean? You have to go from a generalization (REST) to a implementation (REST over HTTP), you cannot assume specifics of a implementation, otherwise there is no point in having generalizations...
                • António Mota
                  To be a little less general and abstract, let me point to a concrete situation. We have a multi protocol REST-ish midleware , where at some point we had the
                  Message 8 of 27 , Mar 24, 2010
                    To be a little less general and abstract, let me point to a concrete situation. We have a multi protocol REST-ish "midleware", where at some point we had the need to extend our HTTP-based uniform interface with one more verb, LISTEN.

                    So the uniform inrterface will be GET, POST, PUT, DELETE, LISTEN.

                    How will one describe the use of LISTEN in a hipermedia/media-type semantic way?

                    _________________________________________________

                    Melhores cumprimentos / Beir beannacht / Best regards

                    António Manuel dos Santos Mota

                    http://card.ly/amsmota
                    _________________________________________________



                    2010/3/24 António Mota <amsmota@...>

                    2010/3/24 Jan Algermissen <algermissen1971@...>

                     


                    On Mar 24, 2010, at 6:17 AM, Kevin Duffey wrote:

                    >
                    >
                    > Hola,
                    >
                    >
                    >
                    > >> I don't agree with this personally. How do I know that I can call PUT, DELETE, GET >>or POST on that one url?
                    >
                    > >Because it's an URL.
                    >
                    > So then, I am forced to make multiple requests to figure out what I can do? Because it's a URL, I hope that a PUT works.. and if it doesn't, I've wasted a round trip to be told it doesn't accept a PUT? That seems really ass backwards to me to be honest.

                    Ask yourself *why* you PUT in the first place. Surely not just to see if something happens - the media types involved will tell you the semantics of link targets (e.g. "this is contact info"). If your intention is to update contact info PUT is the natural thing to do because the HTTP spec tells you so. What other method would you use to update the contact info?

                    But that is what HTTP says, not what REST says. REST mandates a Uniform Interface, not *the* uniform interface GET/PUT/POST/DELETE.

                    There's nothing unrestfull if I decide to create a REST-based architecture with a Uniform Interface compose of XPTA, XPTB, XPTC and XPTD... How, then, you know what is "natural" or not? How, then, do you "formally" associate a media-type with this methods, in terms of semantics?

                    You know what I mean? You have to go from a generalization (REST) to a implementation (REST over HTTP), you cannot assume specifics of a implementation, otherwise there is no point in having generalizations...

                  • Jan Algermissen
                    ... Look at http://tools.ietf.org/html/rfc5789 Jan ... Jan Algermissen, Consultant NORD Software Consulting Mail: algermissen@acm.org Blog:
                    Message 9 of 27 , Mar 24, 2010
                      On Mar 24, 2010, at 11:42 AM, António Mota wrote:

                      > How will one describe the use of LISTEN in a hipermedia/media-type semantic way?

                      Look at http://tools.ietf.org/html/rfc5789

                      Jan


                      -----------------------------------
                      Jan Algermissen, Consultant
                      NORD Software Consulting

                      Mail: algermissen@...
                      Blog: http://www.nordsc.com/blog/
                      Work: http://www.nordsc.com/
                      -----------------------------------
                    • Jan Algermissen
                      ... Neither does HTTP: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9 ... Erm - write specifications... ... REST == arch style, HTTP+URI == an
                      Message 10 of 27 , Mar 24, 2010
                        On Mar 24, 2010, at 11:11 AM, António Mota wrote:

                        > . REST mandates a Uniform Interface, not *the* uniform interface GET/PUT/POST/DELETE.

                        Neither does HTTP:

                        http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9

                        >
                        > There's nothing unrestfull if I decide to create a REST-based architecture with a Uniform Interface compose of XPTA, XPTB, XPTC and XPTD... How, then, you know what is "natural" or not? How, then, do you "formally" associate a media-type with this methods, in terms of semantics?

                        Erm - write specifications...

                        >
                        > You know what I mean? You have to go from a generalization (REST) to a implementation (REST over HTTP),

                        REST == arch style, HTTP+URI == an architecture (of the REST style) Apache, Firefox, Squid etc are implementations of elements (connectors and components) of that architecture.

                        > you cannot assume specifics of a implementation,

                        Sure you can - HTTP specifies such specifics for any implementations of connectors and components. For exampe, HTTP specifies that GET is safe and therefore any component implementation may issue any number of GET request without worrying about side effects.

                        > otherwise there is no point in having generalizations...

                        I do not understand that statement.

                        Jan



                        >
                        >
                        >

                        -----------------------------------
                        Jan Algermissen, Consultant
                        NORD Software Consulting

                        Mail: algermissen@...
                        Blog: http://www.nordsc.com/blog/
                        Work: http://www.nordsc.com/
                        -----------------------------------
                      • António Mota
                        I didn t ask correctly, it s not how to define the method, is how to let clients know where to use that new method by associating it with the semantics of a
                        Message 11 of 27 , Mar 24, 2010
                          I didn't ask correctly, it's not how to define the method, is how to let clients know where to use that new method by associating it with the semantics of a media-type, instead of just do something like

                          <link href="..." method="LISTEN">

                          Sorry for my bad english...

                          _________________________________________________

                          Melhores cumprimentos / Beir beannacht / Best regards

                          António Manuel dos Santos Mota

                          http://card.ly/amsmota
                          _________________________________________________



                          2010/3/24 Jan Algermissen <algermissen1971@...>

                          On Mar 24, 2010, at 11:42 AM, António Mota wrote:

                          > How will one describe the use of LISTEN in a hipermedia/media-type semantic way?

                          Look at http://tools.ietf.org/html/rfc5789

                          Jan


                          -----------------------------------
                           Jan Algermissen, Consultant
                           NORD Software Consulting

                           Mail: algermissen@...
                           Blog: http://www.nordsc.com/blog/
                           Work: http://www.nordsc.com/
                          -----------------------------------





                        • Jan Algermissen
                          ... Not sure what you are looking for, can you explain? Sometimes it makes sense to state sth like: A orders link points to a resource that is a collection
                          Message 12 of 27 , Mar 24, 2010
                            On Mar 24, 2010, at 12:01 PM, António Mota wrote:

                            >
                            >
                            > I didn't ask correctly, it's not how to define the method, is how to let clients know where to use that new method by associating it with the semantics of a media-type,

                            Not sure what you are looking for, can you explain?


                            Sometimes it makes sense to state sth like:

                            "A 'orders' link points to a resource that is a collection of all orders placed. Placing a new order is achieved by POSTing to such a collection"

                            In AtomPub terms you could say:

                            "A collection that accepts application/order contains the placed orders. You can order sth by creating a new order in such a collection (via POST)".



                            For PUT/DELETE you might do sth like:

                            'lock' links refer to lock resources. Creating a new lock results in foo being locked, deletion of the lock resource results in the lock to be removed.

                            No, if you have

                            GET /doc/1

                            200 Ok
                            Link: </doc/1/props?lock>;rel=lock

                            you immediately know that

                            PUT /doc/1/props?lock

                            creates the lock and that

                            DELETE /doc/1/props?lock

                            deletes it.

                            HTH,

                            Jan






                            > instead of just do something like
                            >
                            > <link href="..." method="LISTEN">
                            >
                            > Sorry for my bad english...
                            >
                            > _________________________________________________
                            >
                            > Melhores cumprimentos / Beir beannacht / Best regards
                            >
                            > António Manuel dos Santos Mota
                            >
                            > http://card.ly/amsmota
                            > _________________________________________________
                            >
                            >
                            >
                            > 2010/3/24 Jan Algermissen <algermissen1971@...>
                            >
                            > On Mar 24, 2010, at 11:42 AM, António Mota wrote:
                            >
                            > > How will one describe the use of LISTEN in a hipermedia/media-type semantic way?
                            >
                            > Look at http://tools.ietf.org/html/rfc5789
                            >
                            > Jan
                            >
                            >
                            > -----------------------------------
                            > Jan Algermissen, Consultant
                            > NORD Software Consulting
                            >
                            > Mail: algermissen@...
                            > Blog: http://www.nordsc.com/blog/
                            > Work: http://www.nordsc.com/
                            > -----------------------------------
                            >
                            >
                            >
                            >
                            >
                            >
                            >
                            >

                            -----------------------------------
                            Jan Algermissen, Consultant
                            NORD Software Consulting

                            Mail: algermissen@...
                            Blog: http://www.nordsc.com/blog/
                            Work: http://www.nordsc.com/
                            -----------------------------------
                          • António Mota
                            2010/3/24 Jan Algermissen ... When I said the client I meant the user-agent , I was talking about machine to machine...
                            Message 13 of 27 , Mar 24, 2010
                              2010/3/24 Jan Algermissen <algermissen1971@...>

                              On Mar 24, 2010, at 12:01 PM, António Mota wrote:

                              >
                              >
                              > I didn't ask correctly, it's not how to define the method, is how to let clients know where to use that new method by associating it with the semantics of a media-type,

                              Not sure what you are looking for, can you explain?



                              When I said the "client" I meant the "user-agent", I was talking about machine to machine... Nevertheless, it's not a important question...
                            • Kevin Duffey
                              I think I ve done this before,  but I am working on a service now and want to make sure I am doing it as right as it could be to remain a true REST based
                              Message 14 of 27 , Mar 24, 2010
                                I think I've done this before,  but I am working on a service now and want to make sure I am doing it "as right' as it could be to remain a true REST based API. If this should be under a different thread, that is fine, I just figured it's along the discussion we're having here now.

                                Basically, I have this service that I provide a single URL http://www.mycompany.com/service

                                I thought that a OPTIONS should be requested before anything else? A GET could be used too I suppose, but basically am I understanding correctly that with this single URL, the right call to discover the services that can then be acted on is to send OPTIONS? If not, what is the "right way" a client should make the first call to the initial published URL?

                                In response, I hope I am right in understanding that zero or more services should be returned. How exactly I am still at a loss due to this thread... but how I have my service right now is like such:

                                OPTIONS /service

                                <service>
                                  <links>
                                    <link rel="resource1" href="http://www.mycompany.com/resource1" type="application/vnd.com.mycompany.resource1+xml"/>
                                    <link rel="resource2" href="http://www.mycompany.com/resource2" type="application/vnc.com.mycompany.resource2+xml"/>
                                  </links>
                                </service>

                                Despite what this thread has talked about, I am  not quite sure what to respond with.. which is why the above is what I assumed was ok. Short of knowing prior to the call to the published URL what services are available... I figured this gave back a discoverable list of links that a client can use. Is this correct... if not, please explain what should come back from the published URL. I am also still trying to figure out, from various posts here and other threads, how do you "discover" the media type to set the Content-Type to for specific resources if they don't provide a type="" in the links that are in the response.


                                Now, assuming my above response is not too far off... a client can then use any of those service URLs to, according to Jan I believe post/put/get/delete/head/options to. This is where I was arguing that it would be beneficial to avoid multiple round trips if the above returned with specific methods allowed on a given resource. Regardless of the outcome of that argument, for the sake of this we'll assume that with any resource returned, ALL method types can at be called on it, naturally, with some possibly returning responses that that require yet another call to the server with a different request method. Generally speaking, the initial URL resources should be to a collection, and thus a GET call can pull ALL /resource1 types, a POST to it can create a new one, and a PUT to /resource1/<item> can update an existing one if it exists.. and so on.

                                I'll stop there to avoid continuing on in the wrong direction if that is wrong. I am hoping Jan/et all will provide some constructive criticism and corrections to how the initial first call to the published URL should work.. how it should respond. I'd appreciate an example of XML snippet on what the response would look like if what I have above is incorrect or not RESTful.

                                Thanks all.

                              • Jan Algermissen
                                Kevin, it seems that somewhere along you path into REST you took a wrong turn :-) I suggest you try to erase some assumptions about how it works and start
                                Message 15 of 27 , Mar 24, 2010
                                  Kevin,

                                  it seems that somewhere along you path into REST you took a wrong turn :-) I suggest you try to erase some assumptions about how it works and 'start over'.

                                  Look at AtomPub and OpenSearch and see how the related service documents work; how clients do the discovery with these kinds of services.

                                  Then go to Amazon and analyse yourself while you step through a purchase. Try to view yourself as a machine client and the human targetted links as part of some some online shopping specific media type. Consider Amazon's home page as the service document that tells you where search is, where to browse categories, etc.

                                  Basically, it is all about the media types (and link relations of you use those) you define for your domain. Look at AtomPub service documents which is about the best you can find at the moment.

                                  You can also go and read some stuff I wrote on service documents[1][2]. But I suggest you take a look at the other stuff first.

                                  HTH,

                                  Jan


                                  [1] http://www.nordsc.com/blog/?p=80
                                  [2] http://www.nordsc.com/blog/?cat=13




                                  On Mar 25, 2010, at 12:34 AM, Kevin Duffey wrote:

                                  >
                                  >
                                  > I think I've done this before, but I am working on a service now and want to make sure I am doing it "as right' as it could be to remain a true REST based API. If this should be under a different thread, that is fine, I just figured it's along the discussion we're having here now.
                                  >
                                  > Basically, I have this service that I provide a single URL http://www.mycompany.com/service
                                  >
                                  > I thought that a OPTIONS should be requested before anything else? A GET could be used too I suppose, but basically am I understanding correctly that with this single URL, the right call to discover the services that can then be acted on is to send OPTIONS? If not, what is the "right way" a client should make the first call to the initial published URL?
                                  >
                                  > In response, I hope I am right in understanding that zero or more services should be returned. How exactly I am still at a loss due to this thread... but how I have my service right now is like such:
                                  >
                                  > OPTIONS /service
                                  >
                                  > <service>
                                  > <links>
                                  > <link rel="resource1" href="http://www.mycompany.com/resource1" type="application/vnd.com.mycompany.resource1+xml"/>
                                  > <link rel="resource2" href="http://www.mycompany.com/resource2" type="application/vnc.com.mycompany.resource2+xml"/>
                                  > </links>
                                  > </service>
                                  >
                                  > Despite what this thread has talked about, I am not quite sure what to respond with.. which is why the above is what I assumed was ok. Short of knowing prior to the call to the published URL what services are available... I figured this gave back a discoverable list of links that a client can use. Is this correct... if not, please explain what should come back from the published URL. I am also still trying to figure out, from various posts here and other threads, how do you "discover" the media type to set the Content-Type to for specific resources if they don't provide a type="" in the links that are in the response.
                                  >
                                  >
                                  > Now, assuming my above response is not too far off... a client can then use any of those service URLs to, according to Jan I believe post/put/get/delete/head/options to. This is where I was arguing that it would be beneficial to avoid multiple round trips if the above returned with specific methods allowed on a given resource. Regardless of the outcome of that argument, for the sake of this we'll assume that with any resource returned, ALL method types can at be called on it, naturally, with some possibly returning responses that that require yet another call to the server with a different request method. Generally speaking, the initial URL resources should be to a collection, and thus a GET call can pull ALL /resource1 types, a POST to it can create a new one, and a PUT to /resource1/<item> can update an existing one if it exists.. and so on.
                                  >
                                  > I'll stop there to avoid continuing on in the wrong direction if that is wrong. I am hoping Jan/et all will provide some constructive criticism and corrections to how the initial first call to the published URL should work.. how it should respond. I'd appreciate an example of XML snippet on what the response would look like if what I have above is incorrect or not RESTful.
                                  >
                                  > Thanks all.
                                  >
                                  >
                                  >
                                  >

                                  -----------------------------------
                                  Jan Algermissen, Consultant
                                  NORD Software Consulting

                                  Mail: algermissen@...
                                  Blog: http://www.nordsc.com/blog/
                                  Work: http://www.nordsc.com/
                                  -----------------------------------
                                • Kevin Duffey
                                  Hi Jan, et all, What assumptions exactly am I incorrect on? Having looked at OpenSearch, it s not very clear to me where it shows a walk through from the
                                  Message 16 of 27 , Mar 24, 2010
                                    Hi Jan, et all,

                                    What assumptions exactly am I incorrect on? Having looked at OpenSearch, it's not very clear to me where it shows a walk through from the initial URL request all the way through an example. I did however see the response they return includes <url..> elements with a type="..." that explains the media type for that resource. So I am unclear as to why what I am doing is incorrect.

                                    I am sorry Jan, but your responses don't seem to help much unfortunately. If anything, they confuse me even more.

                                    You've responded on several occasions that it's all about the media types, yet when I ask you how a response that returns with different resources that can be used would instruct a non-human machine on what media type to use when using the resource, I don't get a clear cut example or response. Specifically I am trying to understand how either a human or a machine can make use of one of potentially several different resources it receives from a previous request, and properly set the Content-Type to the right media type when making the request to the resource. If my response returns five different resources that a machine/client can use, and I don't specify media types that are to be set to use those resources, they can't just know it. There has to be a way a machine could discover the right media type to use with no prior info on the resource. If I upgrade my server and add three new resources, the machine/client should be able to use them simply by the <link..> info returned.

                                    Having read several articles/blogs on the subject, along with many threads here, I am simply not digesting the initial published URL request/response.. what the response might look like. If you could be so kind as to provide an example of what a response might look like for a simple webcart service, or some other service, that might offer a few sub-services initially, that would be most beneficial. Prior to all this HATEOAS stuff, I simply provided a SDK document with info on the resources, what they accepted, what they may return, what they were used for. Now it seems the REST/HATEOAS way is to not provide that sort of document, instead just publish a single URL and the client can learn what is possible simply by making a request to this one URL. So throw me a bone here would ya.. don't tell me it's about the media types..I know this.. show me with a simple snippet and some info on the makeup of the response or something to better illustrate this.

                                    Thank you.




                                  • Jan Algermissen
                                    ... Did not say it was incorrect - I only said that you seem to think in too complicated terms. ... What about OpenSearch description and Atom Service
                                    Message 17 of 27 , Mar 24, 2010
                                      On Mar 25, 2010, at 4:35 AM, Kevin Duffey wrote:

                                      >
                                      >
                                      > Hi Jan, et all,
                                      >
                                      > What assumptions exactly am I incorrect on? Having looked at OpenSearch, it's not very clear to me where it shows a walk through from the initial URL request all the way through an example. I did however see the response they return includes <url..> elements with a type="..." that explains the media type for that resource. So I am unclear as to why what I am doing is incorrect.

                                      Did not say it was incorrect - I only said that you seem to think in too complicated terms.

                                      >
                                      > I am sorry Jan, but your responses don't seem to help much unfortunately. If anything, they confuse me even more.

                                      What about OpenSearch description and Atom Service documents? These should explain things pretty well.

                                      >
                                      > You've responded on several occasions that it's all about the media types, yet when I ask you how a response that returns with different resources that can be used would instruct a non-human machine on what media type to use when using the resource, I don't get a clear cut example or response.

                                      That is because at least I do not really understand what you are looking for. What do you mean by "what media type to use when using the resource", for example.

                                      > Specifically I am trying to understand how either a human or a machine can make use of one of potentially several different resources it receives from a previous request, and properly set the Content-Type to the right media type when making the request to the resource.

                                      Which Content-Type? Do you mean the Accept header? Clients should put in there those types they understand and that they think make sense for the given request (use Firebug to trace what FireFox is doing as an example).

                                      > If my response returns five different resources that a machine/client can use, and I don't specify media types that are to be set to use those resources, they can't just know it.

                                      So what? The type attributes are only hints anyway, not guarantees.

                                      > There has to be a way a machine could discover the right media type to use with no prior info on the resource.

                                      It is simple: use those you understand. You will only find out when the request is made which type you actually got.

                                      > If I upgrade my server and add three new resources, the machine/client should be able to use them simply by the <link..> info returned.
                                      >
                                      > Having read several articles/blogs on the subject, along with many threads here, I am simply not digesting the initial published URL request/response.. what the response might look like.

                                      AtomPub service doc, opensearch description doc.... But any other bookmarkable enry state is fine, too. You can use Amazon even if the first interaction is a product page and not the home page, eh?

                                      > If you could be so kind as to provide an example of what a response might look like for a simple webcart service, or some other service, that might offer a few sub-services initially, that would be most beneficial. Prior to all this HATEOAS stuff, I simply provided a SDK document with info on the resources, what they accepted, what they may return, what they were used for. Now it seems the REST/HATEOAS way is to not provide that sort of document, instead just publish a single URL and the client can learn what is possible simply by making a request to this one URL. So throw me a bone here would ya.. don't tell me it's about the media types..I know this.. show me with a simple snippet and some info on the makeup of the response or something to better illustrate this.

                                      Design you media types so that a client can persue its goals from any possible entry point. Amazon for example tells you where you can search on *every* page, not just the home page. So you need not go back to the home page to enter a new search.

                                      Jan


                                      >
                                      > Thank you.
                                      >
                                      >
                                      >
                                      >
                                      >
                                      >
                                      >

                                      -----------------------------------
                                      Jan Algermissen, Consultant
                                      NORD Software Consulting

                                      Mail: algermissen@...
                                      Blog: http://www.nordsc.com/blog/
                                      Work: http://www.nordsc.com/
                                      -----------------------------------
                                    • Kevin Duffey
                                      Hi Jan, ... Ok, can you elaborate on what I am doing that may be construed as too complicated? ... should explain things pretty well. Well, maybe it s just
                                      Message 18 of 27 , Mar 25, 2010
                                        Hi Jan,

                                        >Did not say it was incorrect - I only said that you seem to think in too complicated terms.

                                        Ok, can you elaborate on what I am doing that may be construed as too complicated?


                                        >What about OpenSearch description and Atom Service documents? These
                                        should >explain things pretty well.

                                        Well, maybe it's just me, but the OpenSearch doc is not easy to read for me. I found a few documents, but they aren't really explaining it to my understanding I guess. I've read specs/docs before, but the OpenSearch, unless I am looking at the wrong one, just doesn't give me the info I am seeking to understand this.

                                        >That is because at least I do not really understand what you are looking
                                        for. What do >you mean by "what media type to use when using the resource", for example.

                                        I thought I said... I'll try again. But the atom-pub examples I've seen seem to also return the media type to use. What I mean is.. if I make a GET call to the initial URL (first time client using the API), I am going to get various URLs back to different services available to me (the client) at that time. That initial call has no resource state yet..it's more of a discovery call to the published API service to figure out what is possible.. what resources are available to be called. Each of the URLs I return in the <link..> elements provides the href URL to the service, the rel tag which I don't honestly know what good it does in this specific first call/response, and the type= which is the media type a client will use to specify the Content-Type when making a request to that service. That is what I mean by my <link> elements returning a type. IT lets the client know "this is the media type you must use for this resource URL". It would also be the one set on the Accept header. I don't know if an accompanying document for the API SDK like the OpenSearch Document shows, might explain that if the type is "application/vnd.package.someService+xml" that it ALSO can return generic application/xml if specified as the Accept header.

                                        What I meant by my above statement is that some examples I've seen do NOT return the media type in the <link> element in a response. So, if I were to get back a response that had 8 <link> elements, each to different resources (like search, history, etc), how would I know what to set the Content-Type header to for each of those IF the <link> elements for those resources did not say "for search using application/vnd....search+xml and for history using application/vnd...history+xml"? Without the link elements telling me the type, I would not know what media type to use short of a generic application/xml type. Is that more clear?


                                        >Which Content-Type? Do you mean the Accept header? Clients should
                                        put in there >those types they understand and that they think make sense for the given request (use >Firebug to trace what FireFox is doing as an example).

                                        I don't understand this? How would a client know to use the application/vnd.package.search+xml media type for Content-Type header (and Accept header) for a link with href="http://www.service.com/search"? Nothing in the URL tells me that the media type should be set unless I am to just arbitrarily pull the last word off the end of the URL path and append that to application/vnd... and hope for the best.

                                        >> If my response returns five different resources that a
                                        machine/client can use, and I >>don't specify media types that are to be set to use those resources, they can't just >>know it.

                                        >So what? The
                                        type attributes are only hints anyway, not guarantees.

                                        Huh? What do you mean they are not guarantees? If a link element says type="application/vnd.package.serviceName+xml", why would I not use it.. or why would it only be a hint? What else might it be if it's not what it specifies?

                                        >> There has to be a way a machine could discover the right media type to use with no >>prior info on the resource.

                                        >It is simple: use those you understand. You will only find out when the
                                        request is made >which type you actually got.

                                        Huh? So wait.. I make the initial entry call to the public service URL. I get back a response with some number of <link> elements, each to a different service, specifying a type="" with specific media type to use for that service. It sounds like what you are saying is, if there is no type="" with it, just make a call to it, and it will return back in the Content-Type of the response the media type. So then use that. Is that right?

                                        I don't quite understand tho.. what call am I making to the service? If for example I get back a service named xxyyzz, I set up my request with that URL, I don't know the media type, so I dont' set Content-Type or Accept headers, because I simply don't know yet. I can't possibly know or guess at this point that the media type on the server side is set to handle application/vnd.package.xxyyzz+xml. So when I make a request to the service, it's going to return back with a media type not supported. As I use Jersey on the server side, Jersey wont even get to my service methods that would fill out the response headers properly.. so I wont get back a response with the Content-Type header indicating to me the right media type to use either. So I am no better off. Hence, I am confused short of a link element specifying the media type to use, how you figure it out by just discovering it.. no document, no prior knowledge. How can a machine/bot figure it out?

                                        >AtomPub service doc, opensearch description doc.... But any other bookmarkable enry >state is fine, too. You can use Amazon even if the first interaction is a product page and >not the home page, eh?

                                        I don't know that a web page like amazon is a good example. All the links are using the same media type throughout. In the case of a RESTful API that has more than one service, each service is mapped to a specific media type, it's a bit different to me than a web page with <a href..> links all throughout. I know what you mean by first page is product not home. That is.. if at a later time a client uses a cached URL to a service, not one form the initial API URL, that it should work the same. Agreed. I get that. It fits the cache-able restraint. I planned on every single <link> element throughout my entire API to always return the type="" so that whether its a link resource from the initial public API URL, or a cached link that was called months later, it will respond with the <links> elements with type="" in them so that service calls can be made from that point.

                                        >Design you media types so that a client can persue its goals from any
                                        possible entry >point. Amazon for example tells you where you can search on *every* page, not just the >home page. So you need not go back to the home page to enter a new search.

                                        yes, again.. cached URLs can be entry points later on so need to provide the right info in responses to continue from. I get this. You say "design your media types..." I don't quite know what you mean by that. I think you know Java/Jersey and how you set up a path to a service, and for get/put/delete/post/options, etc you use the annotations on the java methods and so forth. Each service I provide as part of my API would have each method for that service returning with response header of Content-Type set for the media type of that service. I don't understand tho what you mean by design your media types. I assumed that setting the media types this one on the service methods was the design. Responding with the right media type set is also correct as far as I know. So am I missing something?

                                        Thanks Jan.




                                      • Jan Algermissen
                                        ... Because the server might change between you looking at the type atribute and your actual request. The server will tell you what the media type of its
                                        Message 19 of 27 , Mar 26, 2010
                                          On Mar 26, 2010, at 5:58 AM, Kevin Duffey wrote:

                                          >
                                          > >So what? The type attributes are only hints anyway, not guarantees.
                                          >
                                          > Huh? What do you mean they are not guarantees? If a link element says type="application/vnd.package.serviceName+xml", why would I not use it.. or why would it only be a hint?

                                          Because the server might change between you looking at the type atribute and your actual request. The server will tell you what the media type of its response is right there, in the response. And you just need to deal with what you get.
                                          >
                                          > It sounds like what you are saying is, if there is no type="" with it, just make a call to it, and it will return back in the Content-Type of the response the media type. So then use that. Is that right?

                                          Well, of course :-) And even if there is a type attribute it is still the same. A type attribute is just another form of client driven content negotiation that removes the roundtrip you would have with a 300 Multiple Choices response: instead of selecting an alternative from the 300 response's body the server gives you the alternatives up front.

                                          >
                                          > I don't quite understand tho.. what call am I making to the service? If for example I get back a service named xxyyzz, I set up my request with that URL, I don't know the media type, so I dont' set Content-Type or Accept headers, because I simply don't know yet.

                                          Wrong! You know what *you* can handle, right? That is what you put into the Accept header. The Accept header communicates the client's capabilities, not it's assumptions.


                                          > I can't possibly know or guess at this point that the media type on the server side is set to handle application/vnd.package.xxyyzz+xml. So when I make a request to the service, it's going to return back with a media type not supported.

                                          Actually, it should return a 406 Not Aceptable.

                                          > How can a machine/bot figure it out?

                                          As I said: *you* know what *you* can handle. That is what you tell the server.

                                          > You say "design your media types..." I don't quite know what you mean by that.

                                          For example: when you design a machine2machine shopping system, you need one (or several) media types to serialize the application states. Just as you need Atompub/Atom for blogging and OpenSearch for searching, and HTML for human targetted Web pages.

                                          *All* design activity when you create a REST service is specifying (or extending) media types (and/or link relations).


                                          > I think you know Java/Jersey and how you set up a path to a service, and for get/put/delete/post/options, etc you use the annotations on the java methods and so forth. Each service I provide as part of my API would have each method for that service returning with response header of Content-Type set for the media type of that service. I don't understand tho what you mean by design your media types.

                                          Try this thought experiment: write a machine client to Amazon and design a media type application/shopping+xml that provides the necessary semantics for the machine client to e.g. select from a catalogue, compare prices, compare product features, place an order, cacncel an order, obtain a report on past orders, etc.

                                          See http://www.nordsc.com/blog/?cat=13 for a more extensive treatment[1].

                                          Jan


                                          [1] I hope to soon continue that series, I am just too busy with other things

                                          > Thanks Jan.
                                          >
                                          >
                                          >
                                          >
                                          >
                                          >
                                          >

                                          -----------------------------------
                                          Jan Algermissen, Consultant
                                          NORD Software Consulting

                                          Mail: algermissen@...
                                          Blog: http://www.nordsc.com/blog/
                                          Work: http://www.nordsc.com/
                                          -----------------------------------
                                        • Mike Kelly
                                          ... I disagree with that point because the intention of the link (which is what the client cares about) does not alter with regards to changes on the server
                                          Message 20 of 27 , Apr 2, 2010
                                            Jan Algermissen wrote:
                                            > On Mar 26, 2010, at 5:58 AM, Kevin Duffey wrote:
                                            >
                                            >
                                            >>> So what? The type attributes are only hints anyway, not guarantees.
                                            >>>
                                            >> Huh? What do you mean they are not guarantees? If a link element says type="application/vnd.package.serviceName+xml", why would I not use it.. or why would it only be a hint?
                                            >>
                                            >
                                            > Because the server might change between you looking at the type atribute and your actual request. The server will tell you what the media type of its response is right there, in the response. And you just need to deal with what you get.
                                            >

                                            I disagree with that point because the intention of the link (which is
                                            what the client cares about) does not alter with regards to changes on
                                            the server side. I don't see the point in a type attribute if it is not
                                            intended as a 'guarantee' of the correct terms of negotiation for that
                                            step of the application. I agree that it's not intended as a guarantee
                                            of the response but this is due specifically to statelessness and the
                                            way that the conneg mechanism is defined by HTTP.

                                            I can't think of a good reason a client, if it understands such an
                                            attribute, should not alter its Accept header accordingly.


                                            >> It sounds like what you are saying is, if there is no type="" with it, just make a call to it, and it will return back in the Content-Type of the response the media type. So then use that. Is that right?
                                            >>
                                            >
                                            > Well, of course :-) And even if there is a type attribute it is still the same. A type attribute is just another form of client driven content negotiation that removes the roundtrip you would have with a 300 Multiple Choices response: instead of selecting an alternative from the 300 response's body the server gives you the alternatives up front.
                                            >
                                            >

                                            If it's "client driven content negotiation" then why would this not
                                            alter the way clients express their preferences in that given instance
                                            i.e. why would a client not alter their Accept header to reflect the
                                            desire for an application state the link is driving them towards?


                                            >> I don't quite understand tho.. what call am I making to the service? If for example I get back a service named xxyyzz, I set up my request with that URL, I don't know the media type, so I dont' set Content-Type or Accept headers, because I simply don't know yet.
                                            >>
                                            >
                                            > Wrong! You know what *you* can handle, right? That is what you put into the Accept header. The Accept header communicates the client's capabilities, not it's assumptions.
                                            >

                                            Wrong! It communicates client capabilities if, and only if, the
                                            hypermedia driving the client's application state has not been specific
                                            in the given link.

                                            Which is supported by 2616 where the Accept header is defined to
                                            represent the preferences of a *request*, not a client:

                                            " Accept headers can be used to indicate that the request is
                                            specifically limited to a small set of desired types, as in the case of
                                            a request for an in-line image."


                                            Cheers,
                                            Mike
                                          Your message has been successfully submitted and would be delivered to recipients shortly.