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

Re: [rest-discuss] Hypermedia controls

Expand Messages
  • 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 1 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 2 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 3 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 4 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 5 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 6 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 7 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 8 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.