From pmyers at redhat.com Wed Apr 14 18:31:20 2010 From: pmyers at redhat.com (Perry Myers) Date: Wed, 14 Apr 2010 14:31:20 -0400 Subject: [rest-practices] rest-practices purpose Message-ID: <4BC609F8.6020502@redhat.com> I was asked to create and moderate this list with the following purpose in mind... We've got a lot of components in use across Red Hat and the upstream communities that utilize interfaces like QMF and REST. It would be a good thing to have all of the different communities that are producing APIs communicate together to make sure that these API definitions are consistent in both style and usage. This mailing list will focus specifically on best practices for using REST, since we will be providing either native REST interfaces for many of our APIs or layering REST on top of other interfaces like QMF. One other side project is to create a generic QMF<->REST binding in Ruby. Bob M. and Ted R. are leading this and can comment further. Welcome to the list, and if you feel there are others that should participate please feel free to invite them. This is an open and external forum, as we want community observation and involvement as we develop externally consumable APIs using REST. To start with, it might be useful for the existing folks on list that are already creating (have created) REST APIs to provide a little background context about their specific APIs and links to documentation on them. Thanks, Perry From mlittle at redhat.com Thu Apr 15 09:07:28 2010 From: mlittle at redhat.com (Mark Little) Date: Thu, 15 Apr 2010 10:07:28 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BC609F8.6020502@redhat.com> References: <4BC609F8.6020502@redhat.com> Message-ID: <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> Please make sure to include Bill Burke in this. He's our resident REST guru, lead of RESTeasy and author of one of the best REST text books around. Bill is also driving the Red Hat REST-* effort, to try to provide community standards around REST, with the eventual aim to take them to somewhere like IETF or W3C. Mark. On 14 Apr 2010, at 19:31, Perry Myers wrote: > I was asked to create and moderate this list with the following > purpose in > mind... > > We've got a lot of components in use across Red Hat and the upstream > communities that utilize interfaces like QMF and REST. It would be > a good > thing to have all of the different communities that are producing APIs > communicate together to make sure that these API definitions are > consistent in both style and usage. > > This mailing list will focus specifically on best practices for using > REST, since we will be providing either native REST interfaces for > many of > our APIs or layering REST on top of other interfaces like QMF. > > One other side project is to create a generic QMF<->REST binding in > Ruby. > Bob M. and Ted R. are leading this and can comment further. > > Welcome to the list, and if you feel there are others that should > participate please feel free to invite them. This is an open and > external > forum, as we want community observation and involvement as we develop > externally consumable APIs using REST. > > To start with, it might be useful for the existing folks on list > that are > already creating (have created) REST APIs to provide a little > background > context about their specific APIs and links to documentation on them. > > Thanks, > > Perry > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices --- Mark Little mlittle at redhat.com JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland). From markmc at redhat.com Thu Apr 15 11:41:40 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Thu, 15 Apr 2010 12:41:40 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> References: <4BC609F8.6020502@redhat.com> <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> Message-ID: <1271331700.22267.31.camel@blaa> On Thu, 2010-04-15 at 10:07 +0100, Mark Little wrote: > Please make sure to include Bill Burke in this. He's our resident REST > guru, lead of RESTeasy and author of one of the best REST text books > around. Bill is also driving the Red Hat REST-* effort, to try to > provide community standards around REST, with the eventual aim to take > them to somewhere like IETF or W3C. Bill is subscribed and has already drawn up this outline of the kind of things we should consider: https://community.jboss.org/wiki/TheRedHatRESTWiki Mark. From cctrieloff at redhat.com Thu Apr 15 11:53:03 2010 From: cctrieloff at redhat.com (Carl Trieloff) Date: Thu, 15 Apr 2010 07:53:03 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> References: <4BC609F8.6020502@redhat.com> <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> Message-ID: <4BC6FE1F.7010407@redhat.com> Scott has already looped him in. I meet with him wednesday On 04/15/2010 05:07 AM, Mark Little wrote: > Please make sure to include Bill Burke in this. He's our resident REST > guru, lead of RESTeasy and author of one of the best REST text books > around. Bill is also driving the Red Hat REST-* effort, to try to > provide community standards around REST, with the eventual aim to take > them to somewhere like IETF or W3C. > > Mark. > > > On 14 Apr 2010, at 19:31, Perry Myers wrote: > >> I was asked to create and moderate this list with the following >> purpose in >> mind... >> >> We've got a lot of components in use across Red Hat and the upstream >> communities that utilize interfaces like QMF and REST. It would be a >> good >> thing to have all of the different communities that are producing APIs >> communicate together to make sure that these API definitions are >> consistent in both style and usage. >> >> This mailing list will focus specifically on best practices for using >> REST, since we will be providing either native REST interfaces for >> many of >> our APIs or layering REST on top of other interfaces like QMF. >> >> One other side project is to create a generic QMF<->REST binding in >> Ruby. >> Bob M. and Ted R. are leading this and can comment further. >> >> Welcome to the list, and if you feel there are others that should >> participate please feel free to invite them. This is an open and >> external >> forum, as we want community observation and involvement as we develop >> externally consumable APIs using REST. >> >> To start with, it might be useful for the existing folks on list that >> are >> already creating (have created) REST APIs to provide a little background >> context about their specific APIs and links to documentation on them. >> >> Thanks, >> >> Perry >> >> _______________________________________________ >> rest-practices mailing list >> rest-practices at redhat.com >> https://www.redhat.com/mailman/listinfo/rest-practices > > --- > Mark Little > mlittle at redhat.com > > JBoss, by Red Hat > Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod > Street, Windsor, Berkshire, SI4 1TE, United Kingdom. > Registered in UK and Wales under Company Registration No. 3798903 > Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt > Parsons (USA) and Brendan Lane (Ireland). > > > > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From markmc at redhat.com Thu Apr 15 11:54:21 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Thu, 15 Apr 2010 12:54:21 +0100 Subject: [rest-practices] Media types Message-ID: <1271332461.22267.45.camel@blaa> Hey, Okay, I'll take a shot at kicking this off We're beginning to work on defining a RESTful API for RHEV-M here: https://fedorahosted.org/rhevm-api/ One thing we're considering doing is adding new media types for the document formats produced and consumed by the API. Some discussion on that here: https://fedorahosted.org/pipermail/rhevm-api/2010-April/000069.html The main motivation is that it gives us room to make an incompatible change in the document format and allow clients to negotiate which version they require To be clear - we're not planning on making incompatible changes, but it's best to design for the possibility So, the idea is to have e.g. Accept: application/vnd.rht.rhevm.vm+xml;version=1 We would only bump the version number if we make an incompatible change to the format. Clients would not be able to negotiate different compatible format versions Anyway, we should discuss: - Whether this is a sound idea to adopt in general - vnd.rht vs. vnd.redhat vs vnd.com.redhat - Do we need to register these types with the IANA - A single media type to describe all documents returned by the API: application/vnd.rht.rhevm+xml;version=1 or a media type for each entity type: application/vnd.rht.rhevm.vm+xml;version=1 application/vnd.rht.rhevm.host+xml;version=1 application/vnd.rht.rhevm.collection+xml;version=1 or also add media types for each collection type: application/vnd.rht.rhevm.vm+xml;version=1 application/vnd.rht.rhevm.host+xml;version=1 application/vnd.rht.rhevm.collection.vm+xml;version=1 application/vnd.rht.rhevm.collection.host+xml;version=1 - Are modifiers like '+json' and '+yaml' standardised anywhere? Cheers, Mark. From eoghan.glynn at gmail.com Thu Apr 15 12:21:37 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Thu, 15 Apr 2010 13:21:37 +0100 Subject: [rest-practices] Media types In-Reply-To: <1271332461.22267.45.camel@blaa> References: <1271332461.22267.45.camel@blaa> Message-ID: > A single media type to describe all documents returned by the API Interesting question. My initial reaction is that the single application/vnd.com.redhat.rhevm.api+xml media type may indeed be better than a proliferation of more fine-grained types, as really what we're trying to capture here is the "application protocol", which could be thought of in a holistic sense as applying to the entire API. Whereas the individual fine-grained type could be inferred from the entity-body in any case, from say the schema identified in the root xmlns attribute or whatever. So this doesn't need to be necessarily specified in the Content-Type header. A single media type may well be easier to standardize also, if we ever need to evolve it out of the vendor-private space. Cheers, Eoghan On 15 April 2010 12:54, Mark McLoughlin wrote: > Hey, > > Okay, I'll take a shot at kicking this off > > We're beginning to work on defining a RESTful API for RHEV-M here: > > https://fedorahosted.org/rhevm-api/ > > One thing we're considering doing is adding new media types for the > document formats produced and consumed by the API. Some discussion on > that here: > > https://fedorahosted.org/pipermail/rhevm-api/2010-April/000069.html > > The main motivation is that it gives us room to make an incompatible > change in the document format and allow clients to negotiate which > version they require > > To be clear - we're not planning on making incompatible changes, but > it's best to design for the possibility > > So, the idea is to have e.g. > > Accept: application/vnd.rht.rhevm.vm+xml;version=1 > > We would only bump the version number if we make an incompatible change > to the format. Clients would not be able to negotiate different > compatible format versions > > Anyway, we should discuss: > > - Whether this is a sound idea to adopt in general > > - vnd.rht vs. vnd.redhat vs vnd.com.redhat > > - Do we need to register these types with the IANA > > - A single media type to describe all documents returned by the API: > > application/vnd.rht.rhevm+xml;version=1 > > or a media type for each entity type: > > application/vnd.rht.rhevm.vm+xml;version=1 > application/vnd.rht.rhevm.host+xml;version=1 > application/vnd.rht.rhevm.collection+xml;version=1 > > or also add media types for each collection type: > > application/vnd.rht.rhevm.vm+xml;version=1 > application/vnd.rht.rhevm.host+xml;version=1 > application/vnd.rht.rhevm.collection.vm+xml;version=1 > application/vnd.rht.rhevm.collection.host+xml;version=1 > > - Are modifiers like '+json' and '+yaml' standardised anywhere? > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices > -------------- next part -------------- An HTML attachment was scrubbed... URL: From bkearney at redhat.com Thu Apr 15 12:26:41 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Thu, 15 Apr 2010 08:26:41 -0400 Subject: [rest-practices] Media types In-Reply-To: References: <1271332461.22267.45.camel@blaa> Message-ID: <4BC70601.1020005@redhat.com> On 04/15/2010 08:21 AM, Eoghan Glynn wrote: > > > > A single media type to describe all documents returned by the API > > Interesting question. > > My initial reaction is that the single > application/vnd.com.redhat.rhevm.api+xml media type may indeed be better > than a proliferation of more fine-grained types, as really what we're > trying to capture here is the "application protocol", which could be > thought of in a holistic sense as applying to the entire API. > > Whereas the individual fine-grained type could be inferred from the > entity-body in any case, from say the schema identified in the root > xmlns attribute or whatever. So this doesn't need to be necessarily > specified in the Content-Type header. > > A single media type may well be easier to standardize also, if we ever > need to evolve it out of the vendor-private space. > Is media type the preferred model for versioning rather than URL? I could also see /v1/xxxx and /v2/xxxx as means of supporting incompatible versions. -- bk From bburke at redhat.com Thu Apr 15 12:25:50 2010 From: bburke at redhat.com (Bill Burke) Date: Thu, 15 Apr 2010 08:25:50 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BC6FE1F.7010407@redhat.com> References: <4BC609F8.6020502@redhat.com> <1125028E-7BC1-43F9-8AF1-2433BF55D219@redhat.com> <4BC6FE1F.7010407@redhat.com> Message-ID: <4BC705CE.6090302@redhat.com> I'm here. Thanks for invite. Carl Trieloff wrote: > > > Scott has already looped him in. > > I meet with him wednesday -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Thu Apr 15 12:44:57 2010 From: bburke at redhat.com (Bill Burke) Date: Thu, 15 Apr 2010 08:44:57 -0400 Subject: [rest-practices] Media types In-Reply-To: <4BC70601.1020005@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> Message-ID: <4BC70A49.6040104@redhat.com> Bryan Kearney wrote: > On 04/15/2010 08:21 AM, Eoghan Glynn wrote: >> >> >> > A single media type to describe all documents returned by the API >> >> Interesting question. >> >> My initial reaction is that the single >> application/vnd.com.redhat.rhevm.api+xml media type may indeed be better >> than a proliferation of more fine-grained types, as really what we're >> trying to capture here is the "application protocol", which could be >> thought of in a holistic sense as applying to the entire API. >> >> Whereas the individual fine-grained type could be inferred from the >> entity-body in any case, from say the schema identified in the root >> xmlns attribute or whatever. So this doesn't need to be necessarily >> specified in the Content-Type header. >> >> A single media type may well be easier to standardize also, if we ever >> need to evolve it out of the vendor-private space. >> > > Is media type the preferred model for versioning rather than URL? I > could also see /v1/xxxx and /v2/xxxx as means of supporting incompatible > versions. > What I've read is that a different URL scheme might be preferable for clients that are not able to participate in HTTP content negotiation (like a browser). If you're following the guideline of not exposing your URL schemes and instead using links, then things actually become simpler for the client as it doesn't have to set any Accept headers. Another guideline you might want to adopt is to make XML schemas backward and forward compatible. What does this mean? 1) Do not remove XML types or fragments from new versions 2) Allow for *any* new XML elements or attributes in all your XML types. This allows new versions that add new elements to be validated with older schemas. 3) Make any new attributes or elements optional. IMO, there is really no downside to this approach. XML you do not understand you can just ignore. > - Do we need to register these types with the IANA > IMO, wait until you're a bit more mature. > - A single media type to describe all documents returned by the API: > > application/vnd.rht.rhevm+xml;version=1 > You may find that you want more media types to be more explicit to the client of what you are expecting. For example, if you want to use PATCH, your own microformats might be preferred: http://www.subbu.org/blog/2010/04/using-patch Although I personally will probably never use patch: http://bill.burkecentral.com/2010/04/01/links-instead-of-patch I've never liked the idea of having to look into a body of a message to figure out how to process it. This might be important down the road if you need an intermediary that is a transformation engine. > or a media type for each entity type: > > application/vnd.rht.rhevm.vm+xml;version=1 > application/vnd.rht.rhevm.host+xml;version=1 > application/vnd.rht.rhevm.collection+xml;version=1 > > or also add media types for each collection type: > > application/vnd.rht.rhevm.vm+xml;version=1 > application/vnd.rht.rhevm.host+xml;version=1 > application/vnd.rht.rhevm.collection.vm+xml;version=1 > application/vnd.rht.rhevm.collection.host+xml;version=1 > IMO, the above two are ok. Atom does it! applicatoin/atom+xml application/atomcat+xml application/atomsvc+xml > - Are modifiers like '+json' and '+yaml' standardised anywhere? No, but IMO, they should be used. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eoghan.glynn at gmail.com Thu Apr 15 12:53:16 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Thu, 15 Apr 2010 13:53:16 +0100 Subject: [rest-practices] Media types In-Reply-To: <4BC70601.1020005@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> Message-ID: > Is media type the preferred model for versioning rather than URL? Well I guess the answer might be influenced by the choice between a single over-arching media type and many fine-grained types. Because if the former, then specifying the version in the Content-Type would imply the versions of all fine-grained types are rev'd in lock-step. Which may potentially be awkward to maintain. > I could also see /v1/xxxx and /v2/xxxx as means of supporting incompatible versions. Might this approach lead to a higher likelihood of knowledge of the URI structure leaking out to the client side? Cheers, Eoghan On 15 April 2010 13:26, Bryan Kearney wrote: > On 04/15/2010 08:21 AM, Eoghan Glynn wrote: > >> >> >> > A single media type to describe all documents returned by the API >> >> Interesting question. >> >> My initial reaction is that the single >> application/vnd.com.redhat.rhevm.api+xml media type may indeed be better >> than a proliferation of more fine-grained types, as really what we're >> trying to capture here is the "application protocol", which could be >> thought of in a holistic sense as applying to the entire API. >> >> Whereas the individual fine-grained type could be inferred from the >> entity-body in any case, from say the schema identified in the root >> xmlns attribute or whatever. So this doesn't need to be necessarily >> specified in the Content-Type header. >> >> A single media type may well be easier to standardize also, if we ever >> need to evolve it out of the vendor-private space. >> >> > Is media type the preferred model for versioning rather than URL? I could > also see /v1/xxxx and /v2/xxxx as means of supporting incompatible versions. > > -- bk > -------------- next part -------------- An HTML attachment was scrubbed... URL: From bkearney at redhat.com Thu Apr 15 13:03:55 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Thu, 15 Apr 2010 09:03:55 -0400 Subject: [rest-practices] Media types In-Reply-To: References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> Message-ID: <4BC70EBB.60800@redhat.com> On 04/15/2010 08:53 AM, Eoghan Glynn wrote: > > > > Is media type the preferred model for versioning rather than URL? > > Well I guess the answer might be influenced by the choice between a > single over-arching media type and many fine-grained types. Because if > the former, then specifying the version in the Content-Type would imply > the versions of all fine-grained types are rev'd in lock-step. Which may > potentially be awkward to maintain. > > > I could also see /v1/xxxx and /v2/xxxx as means of supporting > incompatible versions. > > Might this approach lead to a higher likelihood of knowledge of the URI > structure leaking out to the client side? It may. I think that this is my one concern around REST as it is today. The client tools today make it easy to string up XML over HTTP iff the clients know the url structure. The lack of an HATEoAS server or client framework makes it much harder to gain adoption (today). However, having said that, the client may know to only following links under /v1. So.. my diatrabe aside.. I think using the high level versions would not prohibit a true REST client. -- bk From bburke at redhat.com Thu Apr 15 13:12:42 2010 From: bburke at redhat.com (Bill Burke) Date: Thu, 15 Apr 2010 09:12:42 -0400 Subject: [rest-practices] Media types In-Reply-To: <4BC70EBB.60800@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70EBB.60800@redhat.com> Message-ID: <4BC710CA.5080102@redhat.com> Bryan Kearney wrote: > On 04/15/2010 08:53 AM, Eoghan Glynn wrote: >> >> >> > Is media type the preferred model for versioning rather than URL? >> >> Well I guess the answer might be influenced by the choice between a >> single over-arching media type and many fine-grained types. Because if >> the former, then specifying the version in the Content-Type would imply >> the versions of all fine-grained types are rev'd in lock-step. Which may >> potentially be awkward to maintain. >> >> > I could also see /v1/xxxx and /v2/xxxx as means of supporting >> incompatible versions. >> >> Might this approach lead to a higher likelihood of knowledge of the URI >> structure leaking out to the client side? > > It may. I think that this is my one concern around REST as it is today. > The client tools today make it easy to string up XML over HTTP iff the > clients know the url structure. The lack of an HATEoAS server or client > framework makes it much harder to gain adoption (today). > This is definitely a problem with RESTEasy's client proxy framework and leads me to believe that I should constrain it a little more and add deeper integration with media type processors like JAXB and Jackson if its possible (JAXB is pretty inflexible). -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bkearney at redhat.com Thu Apr 15 13:41:15 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Thu, 15 Apr 2010 09:41:15 -0400 Subject: [rest-practices] Media types In-Reply-To: <4BC710CA.5080102@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70EBB.60800@redhat.com> <4BC710CA.5080102@redhat.com> Message-ID: <4BC7177B.4070702@redhat.com> On 04/15/2010 09:12 AM, Bill Burke wrote: > > > Bryan Kearney wrote: >> On 04/15/2010 08:53 AM, Eoghan Glynn wrote: >>> >>> >>> > Is media type the preferred model for versioning rather than URL? >>> >>> Well I guess the answer might be influenced by the choice between a >>> single over-arching media type and many fine-grained types. Because if >>> the former, then specifying the version in the Content-Type would imply >>> the versions of all fine-grained types are rev'd in lock-step. Which may >>> potentially be awkward to maintain. >>> >>> > I could also see /v1/xxxx and /v2/xxxx as means of supporting >>> incompatible versions. >>> >>> Might this approach lead to a higher likelihood of knowledge of the URI >>> structure leaking out to the client side? >> >> It may. I think that this is my one concern around REST as it is >> today. The client tools today make it easy to string up XML over HTTP >> iff the clients know the url structure. The lack of an HATEoAS server >> or client framework makes it much harder to gain adoption (today). >> > > This is definitely a problem with RESTEasy's client proxy framework and > leads me to believe that I should constrain it a little more and add > deeper integration with media type processors like JAXB and Jackson if > its possible (JAXB is pretty inflexible). Not just client... server as well. The idea of a single object being used for Hiberante and REST is where I think most folks will start. However, there is a bit of a semantic break where REST would want Links and little to no relationships, where hibernate would want relationships and no links. I also wonder if a notion of url construction ala rails would be nice so I could reference customrUpdateLink(aCustomer). -- bk From bburke at redhat.com Thu Apr 15 13:53:39 2010 From: bburke at redhat.com (Bill Burke) Date: Thu, 15 Apr 2010 09:53:39 -0400 Subject: [rest-practices] Media types In-Reply-To: <4BC7177B.4070702@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70EBB.60800@redhat.com> <4BC710CA.5080102@redhat.com> <4BC7177B.4070702@redhat.com> Message-ID: <4BC71A63.7010207@redhat.com> Bryan Kearney wrote: > On 04/15/2010 09:12 AM, Bill Burke wrote: >> >> >> Bryan Kearney wrote: >>> On 04/15/2010 08:53 AM, Eoghan Glynn wrote: >>>> >>>> >>>> > Is media type the preferred model for versioning rather than URL? >>>> >>>> Well I guess the answer might be influenced by the choice between a >>>> single over-arching media type and many fine-grained types. Because if >>>> the former, then specifying the version in the Content-Type would imply >>>> the versions of all fine-grained types are rev'd in lock-step. Which >>>> may >>>> potentially be awkward to maintain. >>>> >>>> > I could also see /v1/xxxx and /v2/xxxx as means of supporting >>>> incompatible versions. >>>> >>>> Might this approach lead to a higher likelihood of knowledge of the URI >>>> structure leaking out to the client side? >>> >>> It may. I think that this is my one concern around REST as it is >>> today. The client tools today make it easy to string up XML over HTTP >>> iff the clients know the url structure. The lack of an HATEoAS server >>> or client framework makes it much harder to gain adoption (today). >>> >> >> This is definitely a problem with RESTEasy's client proxy framework and >> leads me to believe that I should constrain it a little more and add >> deeper integration with media type processors like JAXB and Jackson if >> its possible (JAXB is pretty inflexible). > > Not just client... server as well. The idea of a single object being > used for Hiberante and REST is where I think most folks will start. > However, there is a bit of a semantic break where REST would want Links > and little to no relationships, where hibernate would want relationships > and no links. I also wonder if a notion of url construction ala rails > would be nice so I could reference customrUpdateLink(aCustomer). > I don't think its a problem from a JAX-RS perspective, but you're right that people will want Hibernate entities and JAXB objects to be one and the same class and this generally might not be the best idea. I think this is more because that the XML will get out of sync with the relational model. I've heard JAX-WS implementations having similar problems. Some RESTEasy contributors have fooled around with the idea of rails-like URL construction. It seemed a little bit fragile to me, so I haven't promoted it so much. BTW, I think this should be in a separate thread. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From markmc at redhat.com Thu Apr 15 16:24:10 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Thu, 15 Apr 2010 17:24:10 +0100 Subject: [rest-practices] Media types In-Reply-To: <4BC70A49.6040104@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> Message-ID: <1271348650.20692.8.camel@blaa> On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: > > Bryan Kearney wrote: > > On 04/15/2010 08:21 AM, Eoghan Glynn wrote: > >> > >> > >> > A single media type to describe all documents returned by the API > >> > >> Interesting question. > >> > >> My initial reaction is that the single > >> application/vnd.com.redhat.rhevm.api+xml media type may indeed be better > >> than a proliferation of more fine-grained types, as really what we're > >> trying to capture here is the "application protocol", which could be > >> thought of in a holistic sense as applying to the entire API. > >> > >> Whereas the individual fine-grained type could be inferred from the > >> entity-body in any case, from say the schema identified in the root > >> xmlns attribute or whatever. So this doesn't need to be necessarily > >> specified in the Content-Type header. > >> > >> A single media type may well be easier to standardize also, if we ever > >> need to evolve it out of the vendor-private space. > >> > > > > Is media type the preferred model for versioning rather than URL? I > > could also see /v1/xxxx and /v2/xxxx as means of supporting incompatible > > versions. > > > > What I've read is that a different URL scheme might be preferable for > clients that are not able to participate in HTTP content negotiation > (like a browser). If you're following the guideline of not exposing > your URL schemes and instead using links, then things actually become > simpler for the client as it doesn't have to set any Accept headers. That works for me Basically, then, version negotiation is done by the client choosing between e.g. Which reminds me: http://tools.ietf.org/html/draft-nottingham-http-link-header-09#section-4.2 Applications that don't wish to register a relation type can use an extension relation type, which is a URI [RFC3986] that uniquely identifies the relation type. So, rather than defining our own custom relation types as strings, we should have a registry of relation types and identify them using URIs? > Another guideline you might want to adopt is to make XML schemas > backward and forward compatible. What does this mean? > > 1) Do not remove XML types or fragments from new versions > 2) Allow for *any* new XML elements or attributes in all your XML types. > This allows new versions that add new elements to be validated with > older schemas. > 3) Make any new attributes or elements optional. > > IMO, there is really no downside to this approach. XML you do not > understand you can just ignore. OTOH, though, that means the validator won't catch even simple typos like which makes the validator rather less useful? How do you imagine clients using the schema? Just chatting with the libvirt guys (DV and danpb) about their schema and they really only see the schema as useful in a client app's unit test suite in order to validate the output of its XML generator i.e. a client app wouldn't use it to validate the XML returned from libvirt, because there's not much the app could do about a validation failure ... > > - Are modifiers like '+json' and '+yaml' standardised anywhere? > > No, but IMO, they should be used. btw, RESTeasy's yaml provider needs e.g. @Produces("application/*+yaml") Cheers, Mark. From markmc at redhat.com Thu Apr 15 16:26:49 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Thu, 15 Apr 2010 17:26:49 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BC609F8.6020502@redhat.com> References: <4BC609F8.6020502@redhat.com> Message-ID: <1271348809.20692.9.camel@blaa> By the way Perry - nice choice of name! :-) Mark. From pmyers at redhat.com Thu Apr 15 17:00:28 2010 From: pmyers at redhat.com (Perry Myers) Date: Thu, 15 Apr 2010 13:00:28 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <1271348809.20692.9.camel@blaa> References: <4BC609F8.6020502@redhat.com> <1271348809.20692.9.camel@blaa> Message-ID: <4BC7462C.2070606@redhat.com> On 04/15/2010 12:26 PM, Mark McLoughlin wrote: > By the way Perry - nice choice of name! :-) Yeah it does have a nice ring to it, though to be completely fair Carl suggested the name so he should get credit for that :) Perry From veillard at redhat.com Fri Apr 16 08:51:12 2010 From: veillard at redhat.com (Daniel Veillard) Date: Fri, 16 Apr 2010 10:51:12 +0200 Subject: [rest-practices] Media types In-Reply-To: <4BC70A49.6040104@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> Message-ID: <20100416085112.GM20291@redhat.com> On Thu, Apr 15, 2010 at 08:44:57AM -0400, Bill Burke wrote: > Bryan Kearney wrote: > >On 04/15/2010 08:21 AM, Eoghan Glynn wrote: > >Is media type the preferred model for versioning rather than URL? > >I could also see /v1/xxxx and /v2/xxxx as means of supporting > >incompatible versions. > > > > What I've read is that a different URL scheme might be preferable > for clients that are not able to participate in HTTP content > negotiation (like a browser). If you're following the guideline of I chime in a bit late, sorry. Agreed, I don't think that the media type is really the right place to carry versioning informations. Even when trying to content negociate this will just confuse the intermediaries. Extra HTTP headers might work (after all it's how your browser tells the server about language options and supported image format). But I tent to think that content negociation makes things way harder (and fragile) than they should. A versioned URI space if you really want to decouple different version support is the simplest IMHO. > not exposing your URL schemes and instead using links, then things > actually become simpler for the client as it doesn't have to set any > Accept headers. > > Another guideline you might want to adopt is to make XML schemas > backward and forward compatible. What does this mean? > > 1) Do not remove XML types or fragments from new versions > 2) Allow for *any* new XML elements or attributes in all your XML > types. This allows new versions that add new elements to be > validated with older schemas. > 3) Make any new attributes or elements optional. > > IMO, there is really no downside to this approach. XML you do not > understand you can just ignore. That's the alternative to versionned URI space, though I would not express that in terms of schemas [1], but in terms of code. Basically the code picks the informations it knows about from the received data and ignores the rest. That how we handle XML parsing in libvirt so far, but there is a danger there, a missing part may change the semantic a lot. To give an specific example we added at some point an extra cache="" attribute to a disk definition of a vm, defining the caching policy, and a client expecting cache="none" to ensure say database data integrity in case of failure may be fooled into believing the server actually accepted and understood that policy, possibly leading to data corruption in case of vm crash. In practice it really worked well for us, but to some extent our stack is a bit more controlled than in a pure web service framework. So if going that route, then more care must be taken when defining evolutions of the XML format. An intermediate way is to allow only unknow attributes on the received XML but not unknown elements, such a generic policy allow to build explicitely compatible and incompatible evolutions with a rather trivial check on the receiving code. Daniel [1] I'm ready to argue about pros and cons of schemas and where they make sense but I'm afraid this can get boring really fast and also off-topic :-) -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel at veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/ From markmc at redhat.com Fri Apr 16 09:22:49 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Fri, 16 Apr 2010 10:22:49 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC70A49.6040104@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> Message-ID: <1271409769.7677.46.camel@blaa> On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: > > application/vnd.rht.rhevm.vm+xml;version=1 > > application/vnd.rht.rhevm.host+xml;version=1 > > application/vnd.rht.rhevm.collection.vm+xml;version=1 > > application/vnd.rht.rhevm.collection.host+xml;version=1 > > > > IMO, the above two are ok. Atom does it! Okay, you're going to need to help me out here :-) We're talking about the format of the document returned by e.g. 'GET /vms'. At the moment, we're just doing: ... You're suggesting using Atom as a generic container format, right? Eoghan suggested something similar here: https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html > application/atom+xml This would just be e.g.: VMs feed 2010-04-16T09:47:55.288+01:00 http://{host}/vms RHEV-M vm2 3 vm3 ... That's simple enough: http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a But now, what about supporting clients who prefer json or yaml? Does "application/atom+json" make much sense, I wonder? > application/atomcat+xml We'd use this to describe e.g. 'vm' and 'host' categories? > application/atomsvc+xml This would be a toplevel feed pointing to our 'vm' and 'host' feeds? Thanks, Mark. From bkearney at redhat.com Fri Apr 16 12:06:16 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Fri, 16 Apr 2010 08:06:16 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <1271409769.7677.46.camel@blaa> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> Message-ID: <4BC852B8.9010101@redhat.com> On 04/16/2010 05:22 AM, Mark McLoughlin wrote: > On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: > >> > application/vnd.rht.rhevm.vm+xml;version=1 >> > application/vnd.rht.rhevm.host+xml;version=1 >> > application/vnd.rht.rhevm.collection.vm+xml;version=1 >> > application/vnd.rht.rhevm.collection.host+xml;version=1 >> > >> >> IMO, the above two are ok. Atom does it! > > Okay, you're going to need to help me out here :-) > > We're talking about the format of the document returned by e.g. > 'GET /vms'. At the moment, we're just doing: > > > > > ... > I think an xml structure like this will make it harder for any auto-clients such as ruby. I would suggest to get as the wrapper. > > You're suggesting using Atom as a generic container format, right? > > Eoghan suggested something similar here: > > https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html > >> application/atom+xml > > This would just be e.g.: > > > > VMs feed > 2010-04-16T09:47:55.288+01:00 > http://{host}/vms > > RHEV-M > > > vm2 > > > > 3 > vm3 > > ... > > > > > That's simple enough: > > http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a > > But now, what about supporting clients who prefer json or yaml? Does > "application/atom+json" make much sense, I wonder? > >> application/atomcat+xml > > We'd use this to describe e.g. 'vm' and 'host' categories? So... one of he items I heard about why REST and not SOAP is that the SOAP envelope is terrible. What I see here is starting to look like such an envelope. Will you be supporting "natrual" xml and json as well? --bk From bmcwhirt at redhat.com Fri Apr 16 12:08:29 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Fri, 16 Apr 2010 08:08:29 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC852B8.9010101@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> Message-ID: Yah, I personally don't like the wrap-it-all-in-atom strategy. Boilerplate is bad. Bob -- Sent from my iPhone On Apr 16, 2010, at 8:06 AM, Bryan Kearney wrote: > On 04/16/2010 05:22 AM, Mark McLoughlin wrote: >> On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: >> >>> > application/vnd.rht.rhevm.vm+xml;version=1 >>> > application/vnd.rht.rhevm.host+xml;version=1 >>> > application/vnd.rht.rhevm.collection.vm+xml;version=1 >>> > application/vnd.rht.rhevm.collection.host+xml;version=1 >>> > >>> >>> IMO, the above two are ok. Atom does it! >> >> Okay, you're going to need to help me out here :-) >> >> We're talking about the format of the document returned by e.g. >> 'GET /vms'. At the moment, we're just doing: >> >> >> >> >> ... >> > > > I think an xml structure like this will make it harder for any auto- > clients such as ruby. I would suggest to get as the wrapper. > >> >> You're suggesting using Atom as a generic container format, right? >> >> Eoghan suggested something similar here: >> >> https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html >> >>> application/atom+xml >> >> This would just be e.g.: >> >> >> >> VMs feed >> 2010-04-16T09:47:55.288+01:00 >> http://{host}/vms >> >> RHEV-M >> >> >> vm2 >> >> >> >> 3 >> vm3 >> >> ... >> >> >> >> >> That's simple enough: >> >> http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a >> >> But now, what about supporting clients who prefer json or yaml? Does >> "application/atom+json" make much sense, I wonder? >> >>> application/atomcat+xml >> >> We'd use this to describe e.g. 'vm' and 'host' categories? > > So... one of he items I heard about why REST and not SOAP is that > the SOAP envelope is terrible. What I see here is starting to look > like such an envelope. Will you be supporting "natrual" xml and json > as well? > > > --bk > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From markmc at redhat.com Fri Apr 16 12:40:42 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Fri, 16 Apr 2010 13:40:42 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC852B8.9010101@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> Message-ID: <1271421642.7677.98.camel@blaa> On Fri, 2010-04-16 at 08:06 -0400, Bryan Kearney wrote: > On 04/16/2010 05:22 AM, Mark McLoughlin wrote: > > On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: > > > >> > application/vnd.rht.rhevm.vm+xml;version=1 > >> > application/vnd.rht.rhevm.host+xml;version=1 > >> > application/vnd.rht.rhevm.collection.vm+xml;version=1 > >> > application/vnd.rht.rhevm.collection.host+xml;version=1 > >> > > >> > >> IMO, the above two are ok. Atom does it! > > > > Okay, you're going to need to help me out here :-) > > > > We're talking about the format of the document returned by e.g. > > 'GET /vms'. At the moment, we're just doing: > > > > > > > > > > ... > > > > > I think an xml structure like this will make it harder for any > auto-clients such as ruby. I would suggest to get as the wrapper. Yeah, is just the JAX-B default from List I was tending towards anyway, but this auto-clients business sounds like an actual concrete reason for it ... I'll have to take a look at that :) > > You're suggesting using Atom as a generic container format, right? > > > > Eoghan suggested something similar here: > > > > https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html > > > >> application/atom+xml > > > > This would just be e.g.: > > > > > > > > VMs feed > > 2010-04-16T09:47:55.288+01:00 > > http://{host}/vms > > > > RHEV-M > > > > > > vm2 > > > > > > > > 3 > > vm3 > > > > ... > > > > > > > > > > That's simple enough: > > > > http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a > > > > But now, what about supporting clients who prefer json or yaml? Does > > "application/atom+json" make much sense, I wonder? > > > >> application/atomcat+xml > > > > We'd use this to describe e.g. 'vm' and 'host' categories? > > So... one of he items I heard about why REST and not SOAP is that the > SOAP envelope is terrible. What I see here is starting to look like such > an envelope. Will you be supporting "natrual" xml and json as well? I'm just exploring what I gather Bill is suggesting. Personally, I think it looks like a pain in the ass for simple clients to handle Cheers, Mark. From bkearney at redhat.com Fri Apr 16 12:46:27 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Fri, 16 Apr 2010 08:46:27 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <1271421642.7677.98.camel@blaa> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <1271421642.7677.98.camel@blaa> Message-ID: <4BC85C23.2010204@redhat.com> On 04/16/2010 08:40 AM, Mark McLoughlin wrote: > On Fri, 2010-04-16 at 08:06 -0400, Bryan Kearney wrote: >> On 04/16/2010 05:22 AM, Mark McLoughlin wrote: >>> On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote: >>> >>>> > application/vnd.rht.rhevm.vm+xml;version=1 >>>> > application/vnd.rht.rhevm.host+xml;version=1 >>>> > application/vnd.rht.rhevm.collection.vm+xml;version=1 >>>> > application/vnd.rht.rhevm.collection.host+xml;version=1 >>>> > >>>> >>>> IMO, the above two are ok. Atom does it! >>> >>> Okay, you're going to need to help me out here :-) >>> >>> We're talking about the format of the document returned by e.g. >>> 'GET /vms'. At the moment, we're just doing: >>> >>> >>> >>> >>> ... >>> >> >> >> I think an xml structure like this will make it harder for any >> auto-clients such as ruby. I would suggest to get as the wrapper. > > Yeah, is just the JAX-B default from List > > I was tending towards anyway, but this auto-clients business > sounds like an actual concrete reason for it ... I'll have to take a > look at that :) We use RESEasy as the server, and I have a small rails app using ActiveResource to test consumers which try and auto-serialize. It is not Hateoas, but it is instructive. -- bk From lutter at redhat.com Fri Apr 16 17:24:58 2010 From: lutter at redhat.com (David Lutterkort) Date: Fri, 16 Apr 2010 10:24:58 -0700 Subject: [rest-practices] Media types In-Reply-To: <1271332461.22267.45.camel@blaa> References: <1271332461.22267.45.camel@blaa> Message-ID: <1271438698.15762.19.camel@localhost> On Thu, 2010-04-15 at 12:54 +0100, Mark McLoughlin wrote: > So, the idea is to have e.g. > > Accept: application/vnd.rht.rhevm.vm+xml;version=1 > > We would only bump the version number if we make an incompatible change > to the format. This seems very cumbersome to me, especially for very simple clients: one of the attractions of REST (over HTTP) is that you can easily whip up a shell script to do very simple things, like list all my VM's and their state. Do I really need to look up the media type just to say 'send me a list of VM's as XML' ? > Clients would not be able to negotiate different > compatible format versions Why have version information in the accept header then anyway ? For HTML, there are two media types: one for XHTML, one for HTML, even though there are multiple versions of either. If you want to indicate fine-grained information about the returned format, either put it in a special HTTP header, or put it into the returned format - once the client knows they are getting XML or JSON, they can easily look for that information. Most clients will ignore that kind of information anyway. David From lutter at redhat.com Fri Apr 16 17:44:41 2010 From: lutter at redhat.com (David Lutterkort) Date: Fri, 16 Apr 2010 10:44:41 -0700 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC852B8.9010101@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> Message-ID: <1271439881.15762.37.camel@localhost> On Fri, 2010-04-16 at 08:06 -0400, Bryan Kearney wrote: > On 04/16/2010 05:22 AM, Mark McLoughlin wrote: > > > > We're talking about the format of the document returned by e.g. > > 'GET /vms'. At the moment, we're just doing: > > > > > > > > > > ... > > > > > I think an xml structure like this will make it harder for any > auto-clients such as ruby. I would suggest to get as the wrapper. Even more importantly, I really don't like using atom links for any kind of relationship - it's really just window-dressing, and makes _no_ semantic difference in the XML, i.e. myvm $properties has no semantic difference from $properties except that it makes processing references, i.e. a representation that has only the id and a link, much more annoying, at least in Ruby. The code to take the first form and turn it into an object that lazy-loads the full properties when given only a reference, you have a much harder time distinguishing between a reference and the full representation (what precisely do you do to determine if $properties is there or not ? Count children of ? Look for an element that has to be there ? Stick $properties into another container tag ?) In the second form, it's very easy: if has no children, it's a reference, if it does have children you're looking at the representation of the whole object. Atom-style links are nice for references to URL's that are not some sort of object in the system, but they're not a particularly nice way to handle object references. David From bburke at redhat.com Fri Apr 16 19:48:28 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 16 Apr 2010 15:48:28 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <1271409769.7677.46.camel@blaa> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> Message-ID: <4BC8BF0C.2040807@redhat.com> Mark McLoughlin wrote: > > This would be a toplevel feed pointing to our 'vm' and 'host' feeds? > If you're in Java land, Jettison (I think Jackson now too) supports outputting JAXB objects as JSON. So, same Java objects modelling atom types can be outputted in JSON. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Fri Apr 16 19:53:19 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 16 Apr 2010 15:53:19 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC852B8.9010101@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> Message-ID: <4BC8C02F.8090208@redhat.com> Bryan Kearney wrote: >> Eoghan suggested something similar here: >> >> https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html >> >>> application/atom+xml >> >> This would just be e.g.: >> >> >> >> VMs feed >> 2010-04-16T09:47:55.288+01:00 >> http://{host}/vms >> >> RHEV-M >> >> >> vm2 >> >> >> >> 3 >> vm3 >> >> ... >> >> >> >> >> That's simple enough: >> >> >> http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a >> >> But now, what about supporting clients who prefer json or yaml? Does >> "application/atom+json" make much sense, I wonder? >> >>> application/atomcat+xml >> >> We'd use this to describe e.g. 'vm' and 'host' categories? > > So... one of he items I heard about why REST and not SOAP is that the > SOAP envelope is terrible. What I see here is starting to look like such > an envelope. Will you be supporting "natrual" xml and json as well? > On one hand maybe somebody wants to listen for updates to VMS. On the other hand, I don't see the point of using Atom for returning collections. It was written as a format for feeds not a collection format. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eoghan.glynn at gmail.com Fri Apr 16 20:12:25 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Fri, 16 Apr 2010 21:12:25 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC8C02F.8090208@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> Message-ID: > On one hand maybe somebody wants to listen for updates to VMS. > > On the other hand, I don't see the point of using Atom for returning collections. It was written as a format for feeds not a collection format. Hi Bill, So just to clarify, the original idea wasn't so much to wrap the VMs collection in an Atom feed, but rather to use a feed to allow clients, having previously executed a query over the VM collection, to receive lightweight notifications of changes to the set of known VMs and their status. For example a new VM appears, the status of another VM changes, a third VM goes away, etc. This would allow clients to update their previous result set, without necessarily re-issueing the original query. It would of course depend on the feed being filtered on the client-side according the original query constraints. To ensure that only genuinely fresh updates were received, idea was to use delta encoding with the cleint setting the "A-IM: feed" header so that it recieves only those entries that were updated later than the If-Modified-Since header (set to the timestamp of the original query or the last GET on the Atom feed, which-ever is the later). It was an open question whether the RESTeasy Atom provider supported delta encoding in this way. I'll need to check this out, unless you know off the top of your head? Cheers, Eoghan On 16 April 2010 20:53, Bill Burke wrote: > > > Bryan Kearney wrote: > >> Eoghan suggested something similar here: >>> >>> https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html >>> >>> application/atom+xml >>>> >>> >>> This would just be e.g.: >>> >>> >>> >>> VMs feed >>> 2010-04-16T09:47:55.288+01:00 >>> http://{host}/vms >>> >>> RHEV-M >>> >>> >>> vm2 >>> >>> >>> >>> 3 >>> vm3 >>> >>> ... >>> >>> >>> >>> >>> That's simple enough: >>> >>> >>> http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a >>> >>> But now, what about supporting clients who prefer json or yaml? Does >>> "application/atom+json" make much sense, I wonder? >>> >>> application/atomcat+xml >>>> >>> >>> We'd use this to describe e.g. 'vm' and 'host' categories? >>> >> >> So... one of he items I heard about why REST and not SOAP is that the SOAP >> envelope is terrible. What I see here is starting to look like such an >> envelope. Will you be supporting "natrual" xml and json as well? >> >> > On one hand maybe somebody wants to listen for updates to VMS. > > On the other hand, I don't see the point of using Atom for returning > collections. It was written as a format for feeds not a collection format. > > > -- > Bill Burke > JBoss, a division of Red Hat > http://bill.burkecentral.com > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices > -------------- next part -------------- An HTML attachment was scrubbed... URL: From bburke at redhat.com Fri Apr 16 20:38:25 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 16 Apr 2010 16:38:25 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> Message-ID: <4BC8CAC1.2090600@redhat.com> Eoghan Glynn wrote: > > > On one hand maybe somebody wants to listen for updates to VMS. > > > > On the other hand, I don't see the point of using Atom for returning > collections. It was written as a format for feeds not a collection format. > > > Hi Bill, > > So just to clarify, the original idea wasn't so much to wrap the VMs > collection in an Atom feed, but rather to use a feed to allow clients, > having previously executed a query over the VM collection, to receive > lightweight notifications of changes to the set of known VMs and their > status. For example a new VM appears, the status of another VM changes, > a third VM goes away, etc. > > This would allow clients to update their previous result set, without > necessarily re-issueing the original query. It would of course depend on > the feed being filtered on the client-side according the original query > constraints. > > To ensure that only genuinely fresh updates were received, idea was to > use delta encoding with the cleint setting the "A-IM: feed" header so > that it recieves only those entries that were updated later than the > If-Modified-Since header (set to the timestamp of the original query or > the last GET on the Atom feed, which-ever is the later). It was an open > question whether the RESTeasy Atom provider supported delta encoding in > this way. I'll need to check this out, unless you know off the top of > your head? > Resteasy's atom support is just a bunch of JAXB classes. The Content class has a bit more logic in that it allows you to extract application-specific JAXB content. That's it. If a content handler was written for this delta type you're talking about, then I could probably easily modify the lightweight Atom classes in RESTEasy to extract the object you're interested in. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eoghan.glynn at gmail.com Fri Apr 16 22:00:25 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Fri, 16 Apr 2010 23:00:25 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC8CAC1.2090600@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> Message-ID: > If a content handler was written for this delta type you're talking about, > then I could probably easily modify the lightweight Atom classes in > RESTEasy to extract the object you're interested in. Hi Bill, I don't think any new type support is needed for the RFC3229+feed idea, rather it would be more a case of just filtering out older entries from the feed, and then marshalling the pruned feed in exactly the same format as before (just with a different status code, 226 "IM Used", and also an extra header IIRC). I guess this filtering could be done manually, but we probably wouldn't want to be creating separate new Feed objects for each different If-Modified-Since timestamp that we see. Cheers, Eoghan On 16 April 2010 21:38, Bill Burke wrote: > > > Eoghan Glynn wrote: > >> >> > On one hand maybe somebody wants to listen for updates to VMS. >> > >> > On the other hand, I don't see the point of using Atom for returning >> collections. It was written as a format for feeds not a collection format. >> >> >> Hi Bill, >> >> So just to clarify, the original idea wasn't so much to wrap the VMs >> collection in an Atom feed, but rather to use a feed to allow clients, >> having previously executed a query over the VM collection, to receive >> lightweight notifications of changes to the set of known VMs and their >> status. For example a new VM appears, the status of another VM changes, a >> third VM goes away, etc. >> >> This would allow clients to update their previous result set, without >> necessarily re-issueing the original query. It would of course depend on the >> feed being filtered on the client-side according the original query >> constraints. >> >> To ensure that only genuinely fresh updates were received, idea was to use >> delta encoding with the cleint setting the "A-IM: feed" header so that it >> recieves only those entries that were updated later than the >> If-Modified-Since header (set to the timestamp of the original query or the >> last GET on the Atom feed, which-ever is the later). It was an open question >> whether the RESTeasy Atom provider supported delta encoding in this way. >> I'll need to check this out, unless you know off the top of your head? >> >> > Resteasy's atom support is just a bunch of JAXB classes. The Content class > has a bit more logic in that it allows you to extract application-specific > JAXB content. That's it. > > If a content handler was written for this delta type you're talking about, > then I could probably easily modify the lightweight Atom classes in RESTEasy > to extract the object you're interested in. > > > -- > Bill Burke > JBoss, a division of Red Hat > http://bill.burkecentral.com > -------------- next part -------------- An HTML attachment was scrubbed... URL: From bburke at redhat.com Fri Apr 16 23:23:01 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 16 Apr 2010 19:23:01 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> Message-ID: <4BC8F155.8010602@redhat.com> Eoghan Glynn wrote: > > > If a content handler was written for this delta type you're talking > about, > > then I could probably easily modify the lightweight Atom classes in > > RESTEasy to extract the object you're interested in. > > > Hi Bill, > > I don't think any new type support is needed for the RFC3229+feed idea, > rather it would be more a case of just filtering out older entries from > the feed, and then marshalling the pruned feed in exactly the same > format as before (just with a different status code, 226 "IM Used", and > also an extra header IIRC). > > I guess this filtering could be done manually, but we probably wouldn't > want to be creating separate new Feed objects for each different > If-Modified-Since timestamp that we see. > Sounds pretty complicated to me. When I hear talk about diff/delta formts and the like (especially with PATCH), I think people are forgetting about both the implementation of these services and what they will be actually doing. The end goal is not to store data in a document file on the server, or to maintain a cache of a document on the client. The end goal is to transform the representation so that it can be consumed by business logic of a specific programming language, and probably stored in a relational database. I guess what I'm saying is that 'boring' is much easier to maintain and re-use than 'clever'. Then again, I may not be understanding exactly what you want. I reread your previous post: > Hi Bill, > > So just to clarify, the original idea wasn't so much to wrap the VMs > collection in an Atom feed, but rather to use a feed to allow clients, > having previously executed a query over the VM collection, to receive > lightweight notifications of changes to the set of known VMs and their > status. For example a new VM appears, the status of another VM changes, > a third VM goes away, etc. > > This would allow clients to update their previous result set, without > necessarily re-issueing the original query. It would of course depend on > the feed being filtered on the client-side according the original query > constraints. > > To ensure that only genuinely fresh updates were received, idea was to > use delta encoding with the cleint setting the "A-IM: feed" header so > that it recieves only those entries that were updated later than the > If-Modified-Since header (set to the timestamp of the original query or > the last GET on the Atom feed, which-ever is the later). It was an open > question whether the RESTeasy Atom provider supported delta encoding in > this way. I'll need to check this out, unless you know off the top of > your head? > > Cheers, > Eoghan I think what you are suggesting (if I'm understanding right) of using If-Modified-Since semantics as a query-like mechanism is overloading the *actual* meaning of this header. This header is meant for conditional reads or updates to save bandwidth (read) or to sequence updates (optimistic concurrency). This header is not meant to be used to get different representations. I guess what I'm saying is that I think the actions should be driven by hypermedia (links) rather than some overloading of HTTP protocols. Which leads me to... In the REST-* messaging work I did, a "next" link header is provided with each event posted to the feed (or topic as is referenced in the spec). This "next" link points to the next *sequenced* event and acts as an index pointing to a specific place in time. This "next" link can point to a future event. (I'm not sure if Atom or RFC5005 has this concept or not of a future event) When the client follows the "next" link the server responds with the sequenced next representation. The response contains a new "next" link that the client follows to retain the sequence. I'm not advocating REST-* Messaging, but, instead trying to illustrate that hypermedia driven interaction is simpler. In this case, the link itself has all the information needed to drive the interaction....And...since its opaque all the client has to know is that this link exists, and to follow it (through a simple GET) to get new information. So, in summary, I think you need 2 separate things: * IMO, keep it simple and define some sort of change-event format that is specific to your domain * Let links be indexes into your event feed instead of overloading the semantics of HTTP Finally, I have no idea if this rant at all answers anything or even pertains to what you are talking about. Apologies if it does not. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eoghan.glynn at gmail.com Sat Apr 17 09:18:07 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Sat, 17 Apr 2010 10:18:07 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC8F155.8010602@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> <4BC8F155.8010602@redhat.com> Message-ID: Yeah, I take your point Bill, I may have been over-gilding the lily ... > I think what you are suggesting (if I'm understanding right) of using If-Modified-Since > semantics as a query-like mechanism is overloading the *actual* meaning of this header. > This header is meant for conditional reads or updates to save bandwidth (read) Yes, there would be a subtle change to the semantics of If-Modified-Since, in the sense of escaping the "all or nothing" straight-jacket. So the idea is to avoid a conditional GET being returned either *nothing*(304 "Not Modified") if not a single entry in the feed has changed, or *everything* (the entire Feed) even if only a relatively small subset of the entries have been updated. You're absolutely correct that this does go against the letter of the spec, which requires that a non-empty return would be exactly the same as for a normal GET. Though I'd argue that the delta semantics are still kinda within the "spirit of the spec" ;) > In the REST-* messaging work I did, a "next" link header is provided with each event > posted to the feed (or topic as is referenced in the spec). This "next" link points to the > next *sequenced* event and acts as an index pointing to a specific place in time. This is interesting, maybe we can structure the provision of updates to the VM collection in a similar way. There was a suggestion previously of taking a paginated approach, but I didn't really like the idea that the state of VMs reported in earlier "pages" could have changed by the time the later "pages" are retrieved. But perhaps explicitly treating the "next" link as a pointer to *future* updates would avoid that sort of messiness. Cheers, Eoghan On 17 April 2010 00:23, Bill Burke wrote: > > > Eoghan Glynn wrote: > >> >> > If a content handler was written for this delta type you're talking >> about, >> > then I could probably easily modify the lightweight Atom classes in >> > RESTEasy to extract the object you're interested in. >> >> >> Hi Bill, >> >> I don't think any new type support is needed for the RFC3229+feed idea, >> rather it would be more a case of just filtering out older entries from the >> feed, and then marshalling the pruned feed in exactly the same format as >> before (just with a different status code, 226 "IM Used", and also an extra >> header IIRC). >> >> I guess this filtering could be done manually, but we probably wouldn't >> want to be creating separate new Feed objects for each different >> If-Modified-Since timestamp that we see. >> >> > Sounds pretty complicated to me. When I hear talk about diff/delta formts > and the like (especially with PATCH), I think people are forgetting about > both the implementation of these services and what they will be actually > doing. The end goal is not to store data in a document file on the server, > or to maintain a cache of a document on the client. The end goal is to > transform the representation so that it can be consumed by business logic of > a specific programming language, and probably stored in a relational > database. I guess what I'm saying is that 'boring' is much easier to > maintain and re-use than 'clever'. > > Then again, I may not be understanding exactly what you want. > > I reread your previous post: > > > > Hi Bill, > > > > So just to clarify, the original idea wasn't so much to wrap the VMs > > collection in an Atom feed, but rather to use a feed to allow clients, > > having previously executed a query over the VM collection, to receive > > lightweight notifications of changes to the set of known VMs and their > > status. For example a new VM appears, the status of another VM changes, > > a third VM goes away, etc. > > > > This would allow clients to update their previous result set, without > > necessarily re-issueing the original query. It would of course depend on > > the feed being filtered on the client-side according the original query > > constraints. > > > > To ensure that only genuinely fresh updates were received, idea was to > > use delta encoding with the cleint setting the "A-IM: feed" header so > > that it recieves only those entries that were updated later than the > > If-Modified-Since header (set to the timestamp of the original query or > > the last GET on the Atom feed, which-ever is the later). It was an open > > question whether the RESTeasy Atom provider supported delta encoding in > > this way. I'll need to check this out, unless you know off the top of > > your head? > > > > Cheers, > > Eoghan > > I think what you are suggesting (if I'm understanding right) of using > If-Modified-Since semantics as a query-like mechanism is overloading the > *actual* meaning of this header. This header is meant for conditional reads > or updates to save bandwidth (read) or to sequence updates (optimistic > concurrency). This header is not meant to be used to get different > representations. > > I guess what I'm saying is that I think the actions should be driven by > hypermedia (links) rather than some overloading of HTTP protocols. Which > leads me to... > > In the REST-* messaging work I did, a "next" link header is provided with > each event posted to the feed (or topic as is referenced in the spec). This > "next" link points to the next *sequenced* event and acts as an index > pointing to a specific place in time. This "next" link can point to a > future event. (I'm not sure if Atom or RFC5005 has this concept or not of a > future event) > > When the client follows the "next" link the server responds with the > sequenced next representation. The response contains a new "next" link that > the client follows to retain the sequence. > > I'm not advocating REST-* Messaging, but, instead trying to illustrate that > hypermedia driven interaction is simpler. In this case, the link itself has > all the information needed to drive the interaction....And...since its > opaque all the client has to know is that this link exists, and to follow it > (through a simple GET) to get new information. > > So, in summary, I think you need 2 separate things: > > * IMO, keep it simple and define some sort of change-event format that is > specific to your domain > * Let links be indexes into your event feed instead of overloading the > semantics of HTTP > > Finally, I have no idea if this rant at all answers anything or even > pertains to what you are talking about. Apologies if it does not. > > > > -- > Bill Burke > JBoss, a division of Red Hat > http://bill.burkecentral.com > -------------- next part -------------- An HTML attachment was scrubbed... URL: From bmcwhirt at redhat.com Sat Apr 17 13:41:24 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Sat, 17 Apr 2010 09:41:24 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> <4BC8F155.8010602@redhat.com> Message-ID: <93583FF6-F40C-46EF-8DF2-0710A93EFAFD@redhat.com> > You're absolutely correct that this does go against the letter of > the spec, which requires that a non-empty return would be exactly > the same as for a normal GET. > > Though I'd argue that the delta semantics are still kinda within the > "spirit of the spec" ;) I dunno if Squid or other http proxies and caches would agree with that though. We gotta live within existing deployed http infrastructure. Bob > > > In the REST-* messaging work I did, a "next" link header is > provided with each event > > posted to the feed (or topic as is referenced in the spec). This > "next" link points to the > > next *sequenced* event and acts as an index pointing to a specific > place in time. > > This is interesting, maybe we can structure the provision of updates > to the VM collection in a similar way. There was a suggestion > previously of taking a paginated approach, but I didn't really like > the idea that the state of VMs reported in earlier "pages" could > have changed by the time the later "pages" are retrieved. But > perhaps explicitly treating the "next" link as a pointer to future > updates would avoid that sort of messiness. > > Cheers, > Eoghan > > On 17 April 2010 00:23, Bill Burke wrote: > > > Eoghan Glynn wrote: > > > If a content handler was written for this delta type you're > talking about, > > then I could probably easily modify the lightweight Atom classes in > > RESTEasy to extract the object you're interested in. > > > Hi Bill, > > I don't think any new type support is needed for the RFC3229+feed > idea, rather it would be more a case of just filtering out older > entries from the feed, and then marshalling the pruned feed in > exactly the same format as before (just with a different status > code, 226 "IM Used", and also an extra header IIRC). > > I guess this filtering could be done manually, but we probably > wouldn't want to be creating separate new Feed objects for each > different If-Modified-Since timestamp that we see. > > > Sounds pretty complicated to me. When I hear talk about diff/delta > formts and the like (especially with PATCH), I think people are > forgetting about both the implementation of these services and what > they will be actually doing. The end goal is not to store data in a > document file on the server, or to maintain a cache of a document on > the client. The end goal is to transform the representation so that > it can be consumed by business logic of a specific programming > language, and probably stored in a relational database. I guess > what I'm saying is that 'boring' is much easier to maintain and re- > use than 'clever'. > > Then again, I may not be understanding exactly what you want. > > I reread your previous post: > > > > Hi Bill, > > > > So just to clarify, the original idea wasn't so much to wrap the VMs > > collection in an Atom feed, but rather to use a feed to allow > clients, > > having previously executed a query over the VM collection, to > receive > > lightweight notifications of changes to the set of known VMs and > their > > status. For example a new VM appears, the status of another VM > changes, > > a third VM goes away, etc. > > > > This would allow clients to update their previous result set, > without > > necessarily re-issueing the original query. It would of course > depend on > > the feed being filtered on the client-side according the original > query > > constraints. > > > > To ensure that only genuinely fresh updates were received, idea > was to > > use delta encoding with the cleint setting the "A-IM: feed" header > so > > that it recieves only those entries that were updated later than the > > If-Modified-Since header (set to the timestamp of the original > query or > > the last GET on the Atom feed, which-ever is the later). It was an > open > > question whether the RESTeasy Atom provider supported delta > encoding in > > this way. I'll need to check this out, unless you know off the top > of > > your head? > > > > Cheers, > > Eoghan > > I think what you are suggesting (if I'm understanding right) of > using If-Modified-Since semantics as a query-like mechanism is > overloading the *actual* meaning of this header. This header is > meant for conditional reads or updates to save bandwidth (read) or > to sequence updates (optimistic concurrency). This header is not > meant to be used to get different representations. > > I guess what I'm saying is that I think the actions should be driven > by hypermedia (links) rather than some overloading of HTTP > protocols. Which leads me to... > > In the REST-* messaging work I did, a "next" link header is provided > with each event posted to the feed (or topic as is referenced in the > spec). This "next" link points to the next *sequenced* event and > acts as an index pointing to a specific place in time. This "next" > link can point to a future event. (I'm not sure if Atom or RFC5005 > has this concept or not of a future event) > > When the client follows the "next" link the server responds with the > sequenced next representation. The response contains a new "next" > link that the client follows to retain the sequence. > > I'm not advocating REST-* Messaging, but, instead trying to > illustrate that hypermedia driven interaction is simpler. In this > case, the link itself has all the information needed to drive the > interaction....And...since its opaque all the client has to know is > that this link exists, and to follow it (through a simple GET) to > get new information. > > So, in summary, I think you need 2 separate things: > > * IMO, keep it simple and define some sort of change-event format > that is specific to your domain > * Let links be indexes into your event feed instead of overloading > the semantics of HTTP > > Finally, I have no idea if this rant at all answers anything or even > pertains to what you are talking about. Apologies if it does not. > > > > -- > Bill Burke > JBoss, a division of Red Hat > http://bill.burkecentral.com > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices -------------- next part -------------- An HTML attachment was scrubbed... URL: From bburke at redhat.com Sat Apr 17 15:00:51 2010 From: bburke at redhat.com (Bill Burke) Date: Sat, 17 Apr 2010 11:00:51 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <93583FF6-F40C-46EF-8DF2-0710A93EFAFD@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> <4BC8F155.8010602@redhat.com> <93583FF6-F40C-46EF-8DF2-0710A93EFAFD@redhat.com> Message-ID: <4BC9CD23.9080500@redhat.com> Bob McWhirter wrote: >> You're absolutely correct that this does go against the letter of the >> spec, which requires that a non-empty return would be exactly the same >> as for a normal GET. >> >> Though I'd argue that the delta semantics are still kinda within the >> "spirit of the spec" ;) > > I dunno if Squid or other http proxies and caches would agree with that > though. We gotta live within existing deployed http infrastructure. > That's an even better reason why this isn't a good idea. You'd never be able to effectively insert a cache if you had special semantics tied to if-modified-since. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Sat Apr 17 15:01:09 2010 From: bburke at redhat.com (Bill Burke) Date: Sat, 17 Apr 2010 11:01:09 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> <4BC8F155.8010602@redhat.com> Message-ID: <4BC9CD35.40906@redhat.com> Eoghan Glynn wrote: > > Yeah, I take your point Bill, I may have been over-gilding the lily ... > > > I think what you are suggesting (if I'm understanding right) of using > If-Modified-Since > > semantics as a query-like mechanism is overloading the *actual* > meaning of this header. > > This header is meant for conditional reads or updates to save > bandwidth (read) > > Yes, there would be a subtle change to the semantics of > If-Modified-Since, in the sense of escaping the "all or nothing" > straight-jacket. > > So the idea is to avoid a conditional GET being returned either > /nothing/ (304 "Not Modified") if not a single entry in the feed has > changed, or /everything/ (the entire Feed) even if only a relatively > small subset of the entries have been updated. > > You're absolutely correct that this does go against the letter of the > spec, which requires that a non-empty return would be exactly the same > as for a normal GET. > > Though I'd argue that the delta semantics are still kinda within the > "spirit of the spec" ;) > > > In the REST-* messaging work I did, a "next" link header is provided > with each event > > posted to the feed (or topic as is referenced in the spec). This > "next" link points to the > > next *sequenced* event and acts as an index pointing to a specific > place in time. > > This is interesting, maybe we can structure the provision of updates to > the VM collection in a similar way. There was a suggestion previously of > taking a paginated approach, but I didn't really like the idea that the > state of VMs reported in earlier "pages" could have changed by the time > the later "pages" are retrieved. But perhaps explicitly treating the > "next" link as a pointer to /future/ updates would avoid that sort of > messiness. > I'm not sure what the end goal is here. Are you interested in always getting the latest view of the VM collection? Or are you interested in each change event that happened to the collection? If its the former, then a conditional GET using if-modified-since or if-not-match is the best approach even if there are query parameters (I'm pretty sure caches are ok with query parameters). If its the latter, a link approach is better IMO. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eoghan.glynn at gmail.com Sat Apr 17 17:02:33 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Sat, 17 Apr 2010 18:02:33 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC9CD35.40906@redhat.com> References: <1271332461.22267.45.camel@blaa> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> <4BC8CAC1.2090600@redhat.com> <4BC8F155.8010602@redhat.com> <4BC9CD35.40906@redhat.com> Message-ID: > That's an even better reason why this isn't a good idea. You'd never be able to > effectively insert a cache if you had special semantics tied to if-modified-since. OK, thanks Bob & Bill for the clarification, it now fairly clear that the delta encoding route is not the way to go. > Are you interested in always getting the latest view of the VM collection? > Or are you interested in each change event that happened to the collection? Yes and yes ;) The idea was to get an initial collection of VMs satisfying certain criteria, but then to also retrieve updates as the status of the VM collection changes, without necessarily re-evaluating the entire query. So I'm thinking now of a simpler alternative approach that uses neither If-Modified-Since nor Atom (as the conduit to push out updates). I'll flesh these ideas out on Monday and do some prototyping. Cheers, Eoghan On 17 April 2010 16:01, Bill Burke wrote: > > > Eoghan Glynn wrote: > >> >> Yeah, I take your point Bill, I may have been over-gilding the lily ... >> >> > I think what you are suggesting (if I'm understanding right) of using >> If-Modified-Since >> > semantics as a query-like mechanism is overloading the *actual* meaning >> of this header. >> > This header is meant for conditional reads or updates to save bandwidth >> (read) >> >> Yes, there would be a subtle change to the semantics of If-Modified-Since, >> in the sense of escaping the "all or nothing" straight-jacket. >> >> So the idea is to avoid a conditional GET being returned either /nothing/ >> (304 "Not Modified") if not a single entry in the feed has changed, or >> /everything/ (the entire Feed) even if only a relatively small subset of the >> entries have been updated. >> >> You're absolutely correct that this does go against the letter of the >> spec, which requires that a non-empty return would be exactly the same as >> for a normal GET. >> >> Though I'd argue that the delta semantics are still kinda within the >> "spirit of the spec" ;) >> >> > In the REST-* messaging work I did, a "next" link header is provided >> with each event >> > posted to the feed (or topic as is referenced in the spec). This >> "next" link points to the >> > next *sequenced* event and acts as an index pointing to a specific >> place in time. >> >> This is interesting, maybe we can structure the provision of updates to >> the VM collection in a similar way. There was a suggestion previously of >> taking a paginated approach, but I didn't really like the idea that the >> state of VMs reported in earlier "pages" could have changed by the time the >> later "pages" are retrieved. But perhaps explicitly treating the "next" link >> as a pointer to /future/ updates would avoid that sort of messiness. >> >> > I'm not sure what the end goal is here. Are you interested in always > getting the latest view of the VM collection? Or are you interested in each > change event that happened to the collection? If its the former, then a > conditional GET using if-modified-since or if-not-match is the best approach > even if there are query parameters (I'm pretty sure caches are ok with query > parameters). If its the latter, a link approach is better IMO. > > > -- > Bill Burke > JBoss, a division of Red Hat > http://bill.burkecentral.com > -------------- next part -------------- An HTML attachment was scrubbed... URL: From markmc at redhat.com Mon Apr 19 13:19:22 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Mon, 19 Apr 2010 14:19:22 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BC8C02F.8090208@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <4BC8C02F.8090208@redhat.com> Message-ID: <1271683162.2830.3.camel@blaa> On Fri, 2010-04-16 at 15:53 -0400, Bill Burke wrote: > > Bryan Kearney wrote: > >> Eoghan suggested something similar here: > >> > >> https://fedorahosted.org/pipermail/rhevm-api/2010-April/000025.html > >> > >>> application/atom+xml > >> > >> This would just be e.g.: > >> > >> > >> > >> VMs feed > >> 2010-04-16T09:47:55.288+01:00 > >> http://{host}/vms > >> > >> RHEV-M > >> > >> > >> vm2 > >> > >> > >> > >> 3 > >> vm3 > >> > >> ... > >> > >> > >> > >> > >> That's simple enough: > >> > >> > >> http://git.fedoraproject.org/git/?p=rhevm-api.git;a=commitdiff;h=3fff835a > >> > >> But now, what about supporting clients who prefer json or yaml? Does > >> "application/atom+json" make much sense, I wonder? > >> > >>> application/atomcat+xml > >> > >> We'd use this to describe e.g. 'vm' and 'host' categories? > > > > So... one of he items I heard about why REST and not SOAP is that the > > SOAP envelope is terrible. What I see here is starting to look like such > > an envelope. Will you be supporting "natrual" xml and json as well? > > > > On one hand maybe somebody wants to listen for updates to VMS. > > On the other hand, I don't see the point of using Atom for returning > collections. It was written as a format for feeds not a collection format. Ah, Eoghan just pointed out how we got our wires crossed here I read "Atom does it!" as "Atom is perfect as a generic container" rather than (what you intended) "Atom has multiple media types" Good - I was extremely dubious about using Atom for all collections Cheers, Mark. From eglynn at redhat.com Mon Apr 19 19:20:43 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Mon, 19 Apr 2010 20:20:43 +0100 Subject: [rest-practices] Async operations and statelessness Message-ID: <1271704843.3965.20.camel@quark> Hi Folks, I wanted to get your feeling on the question of breaking statelessness when asynchronous operations are used, in particular in terms of the protocol used to check the outcome of the deferred task. So say we need to model a potentially long-lived operation, such as migrating a VM. To avoid tying up a connection for the duration, the server could respond to the "POST /vms/999/reboot" request with a 202 Accepted, along with a unique URI to be used subsequently to check on the status of the migration. Now it's the lifecycle of the temporary resource represented by this URI that seems to be potentially problematic. While the async operation is still in flight, there's no problem. However the question is how long _after_ the operation has completed should we maintain this resource so that the client can eventually determine the outcome? We've no guarantee that the client will poll regularly, so say we impose some arbitrary expiry, maybe 10 minutes after the task has completed. But even for that limited time we seem to be breaking one of the fundamental Fielding commandments, the one that demands session state is kept entirely on the client side. After the task completes, this URI no longer represents a resource per se, rather we'd just be keeping it around for a while to support our conversation with the client. So another more extreme approach would be to limit the client to: (a) checking whether the async operation is still being processed, so that the status URI is only valid until the task completes, (b) inferring from the current state of the VM whether the task may have succeeded or failed, for example the client gets a big hint that its stop operation has failed if the task has completed but the VM state hasn't transitioned to DOWN (or course there's a race here, as the VM may simply have been restarted in the meantime by another agent), and, (c) getting a indirect indication of the failure reason by scanning an event/audit log. Obviously the stricter approach makes life a lot more awkward for the client, whereas the stateful approach would be much more convenient. Feedback welcome! Cheers, Eoghan From bburke at redhat.com Mon Apr 19 19:53:56 2010 From: bburke at redhat.com (Bill Burke) Date: Mon, 19 Apr 2010 15:53:56 -0400 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <1271704843.3965.20.camel@quark> References: <1271704843.3965.20.camel@quark> Message-ID: <4BCCB4D4.60609@redhat.com> Why not just redirect to the VM resource URL? Then you just see the state of the VM as: ... BOOTING FAILED BOOT ... ... RUNNING Even if you create a specific resource for the action, I don't understand why it would be stateful? Its not session oriented, it is modeling the state of the VM. Any concurrent reboot would just redirect to this new boot resource or just throw 412 with a message that the vm is already being booted or something like that. Eoghan Glynn wrote: > Hi Folks, > > I wanted to get your feeling on the question of breaking statelessness > when asynchronous operations are used, in particular in terms of the > protocol used to check the outcome of the deferred task. > > So say we need to model a potentially long-lived operation, such as > migrating a VM. To avoid tying up a connection for the duration, the > server could respond to the "POST /vms/999/reboot" request with a 202 > Accepted, along with a unique URI to be used subsequently to check on > the status of the migration. > > Now it's the lifecycle of the temporary resource represented by this URI > that seems to be potentially problematic. While the async operation is > still in flight, there's no problem. However the question is how long > _after_ the operation has completed should we maintain this resource so > that the client can eventually determine the outcome? We've no guarantee > that the client will poll regularly, so say we impose some arbitrary > expiry, maybe 10 minutes after the task has completed. But even for that > limited time we seem to be breaking one of the fundamental Fielding > commandments, the one that demands session state is kept entirely on the > client side. After the task completes, this URI no longer represents a > resource per se, rather we'd just be keeping it around for a while to > support our conversation with the client. > > So another more extreme approach would be to limit the client to: > > (a) checking whether the async operation is still being processed, so > that the status URI is only valid until the task completes, > > (b) inferring from the current state of the VM whether the task may have > succeeded or failed, for example the client gets a big hint that its > stop operation has failed if the task has completed but the VM state > hasn't transitioned to DOWN (or course there's a race here, as the VM > may simply have been restarted in the meantime by another agent), > > and, > > (c) getting a indirect indication of the failure reason by scanning an > event/audit log. > > Obviously the stricter approach makes life a lot more awkward for the > client, whereas the stateful approach would be much more convenient. > > Feedback welcome! > > Cheers, > Eoghan > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From eglynn at redhat.com Mon Apr 19 20:27:11 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Mon, 19 Apr 2010 21:27:11 +0100 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <4BCCB4D4.60609@redhat.com> References: <1271704843.3965.20.camel@quark> <4BCCB4D4.60609@redhat.com> Message-ID: <1271708831.3965.43.camel@quark> Thanks for the feedback, Bill, some comments in-line ... On Mon, 2010-04-19 at 15:53 -0400, Bill Burke wrote: > Why not just redirect to the VM resource URL? Then you just see the > state of the VM as: > > > ... > > BOOTING > > > > > > > FAILED BOOT > > ... > > > > ... > > RUNNING > > Yeah, that's what I kinda meant by limitation (b). But wouldn't there be a race condition in that a second client could have come along in the meantime and initiated another action that could overwrite the state change flowing from the first client's action? >From the point of view of an individual user, they'd probably be most interested in knowing whether _their_ action succeeded or failed, not so much how the _most recent_ action applied to the VM panned out. > Even if you create a specific resource for the action, I don't > understand why it would be stateful? Its not session oriented, it is > modeling the state of the VM. Well it seemed to me that its more modeling the outcome of a particular action applied to the VM, as opposed to the VM itself. So you could think of the current VM state being the result of a whole sequence of actions, with more recent operations undoing the effect of older ones. Keeping the outcome of past state transitions around just to facilitate the clients that initiated the corresponding actions seems just a tad sessioney to me. But perhaps its OK if we think of it in terms of an audit/event log, so that URI handed out to the client gives it the ability to search the log for all related events for example, or points to the "future" audit record that'll be written on completion. > Any concurrent reboot would just redirect > to this new boot resource or just throw 412 with a message that the vm > is already being booted or something like that. Yeah, if the subsequent operation really was concurrent, then that would work. But the problematic case would be where a subsequent state change sneaks in between the first operation completing and the client getting around to check on the outcome. I may be making a mountain out of a mole-hill here. In which case, I'd be happy to follow the simpler approach. Cheers, Eoghan > > Eoghan Glynn wrote: > > Hi Folks, > > > > I wanted to get your feeling on the question of breaking statelessness > > when asynchronous operations are used, in particular in terms of the > > protocol used to check the outcome of the deferred task. > > > > So say we need to model a potentially long-lived operation, such as > > migrating a VM. To avoid tying up a connection for the duration, the > > server could respond to the "POST /vms/999/reboot" request with a 202 > > Accepted, along with a unique URI to be used subsequently to check on > > the status of the migration. > > > > Now it's the lifecycle of the temporary resource represented by this URI > > that seems to be potentially problematic. While the async operation is > > still in flight, there's no problem. However the question is how long > > _after_ the operation has completed should we maintain this resource so > > that the client can eventually determine the outcome? We've no guarantee > > that the client will poll regularly, so say we impose some arbitrary > > expiry, maybe 10 minutes after the task has completed. But even for that > > limited time we seem to be breaking one of the fundamental Fielding > > commandments, the one that demands session state is kept entirely on the > > client side. After the task completes, this URI no longer represents a > > resource per se, rather we'd just be keeping it around for a while to > > support our conversation with the client. > > > > So another more extreme approach would be to limit the client to: > > > > (a) checking whether the async operation is still being processed, so > > that the status URI is only valid until the task completes, > > > > (b) inferring from the current state of the VM whether the task may have > > succeeded or failed, for example the client gets a big hint that its > > stop operation has failed if the task has completed but the VM state > > hasn't transitioned to DOWN (or course there's a race here, as the VM > > may simply have been restarted in the meantime by another agent), > > > > and, > > > > (c) getting a indirect indication of the failure reason by scanning an > > event/audit log. > > > > Obviously the stricter approach makes life a lot more awkward for the > > client, whereas the stateful approach would be much more convenient. > > > > Feedback welcome! > > > > Cheers, > > Eoghan > > > > _______________________________________________ > > rest-practices mailing list > > rest-practices at redhat.com > > https://www.redhat.com/mailman/listinfo/rest-practices > From markmc at redhat.com Tue Apr 20 12:59:55 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 20 Apr 2010 13:59:55 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <1271439881.15762.37.camel@localhost> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <1271439881.15762.37.camel@localhost> Message-ID: <1271768396.2830.51.camel@blaa> On Fri, 2010-04-16 at 10:44 -0700, David Lutterkort wrote: > On Fri, 2010-04-16 at 08:06 -0400, Bryan Kearney wrote: > > On 04/16/2010 05:22 AM, Mark McLoughlin wrote: > > > > > > We're talking about the format of the document returned by e.g. > > > 'GET /vms'. At the moment, we're just doing: > > > > > > > > > > > > > > > ... > > > > > > > > > I think an xml structure like this will make it harder for any > > auto-clients such as ruby. I would suggest to get as the wrapper. > > Even more importantly, I really don't like using atom links for any kind > of relationship - it's really just window-dressing, and makes _no_ > semantic difference in the XML, i.e. > > > > myvm > $properties > > > has no semantic difference from > > > $properties > > > except that it makes processing references, i.e. a representation that > has only the id and a link, much more annoying, at least in Ruby. Could you give some example code, maybe? I've just had a quick look at the ruby rest client, and it's not immediately obvious what you mean > The code to take the first form and turn it into an object that > lazy-loads the full properties when given only a reference, you have a > much harder time distinguishing between a reference and the full > representation (what precisely do you do to determine if $properties is > there or not ? Count children of ? Look for an element that has to > be there ? Stick $properties into another container tag ?) Using e.g. as a 'reference' strikes me as as the real problem here - you're struggling to tell whether a node is a representation of the object, or just a reference to the object i.e. and its much more obvious the former is a reference > In the second form, it's very easy: if has no children, it's a > reference, if it does have children you're looking at the representation > of the whole object. Alternative for this 'lazy loading' thing: if has a single rel="self" , it is incomplete > Atom-style links are nice for references to URL's that are not some sort > of object in the system, What are they, then? By giving them a URI, we're modelling actions as objects too :-) > but they're not a particularly nice way to handle object references. Bill makes the case for Atom links in his book and I agree it makes some sense. But I actually don't particularly care - we're designing a new API and trying to stick with the 'consensus approach' rather than going and re-inventing the wheel. Cheers, Mark. From eglynn at redhat.com Tue Apr 20 14:22:14 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Tue, 20 Apr 2010 15:22:14 +0100 Subject: [rest-practices] Read-only fields in a representation type Message-ID: <1271773334.3965.84.camel@quark> Folks, A REST design question ... suppose we're using the same representation in a number of different contexts: 1. to capture client input to resource creation (i.e. the payload in the POST /collection request) 2. to encode a state change initiated by the client (i.e. the payload for the PUT /collection/id request) 3. to represent the complete resource state sent back to the client (i.e. response to GET /collection/id) Say the representations used in cases #1 and #2 are a proper subset of #3, because some of the fields must be computed, or have fixed defaults/initial values. So the question is, how do we enforce this constraint? We could define separate types to ensure that only those fields that really can be set by the client are used in the POST and PUT, and then enforce via schema validation or whatever. Or is best to be tolerant and just silently discard any read-only fields specified in the first two cases? Cheers, Eoghan From bkearney at redhat.com Tue Apr 20 12:42:59 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Tue, 20 Apr 2010 08:42:59 -0400 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <1271704843.3965.20.camel@quark> References: <1271704843.3965.20.camel@quark> Message-ID: <4BCDA153.5090401@redhat.com> On 04/19/2010 03:20 PM, Eoghan Glynn wrote: > > Hi Folks, > > I wanted to get your feeling on the question of breaking statelessness > when asynchronous operations are used, in particular in terms of the > protocol used to check the outcome of the deferred task. > > So say we need to model a potentially long-lived operation, such as > migrating a VM. To avoid tying up a connection for the duration, the > server could respond to the "POST /vms/999/reboot" request with a 202 > Accepted, along with a unique URI to be used subsequently to check on > the status of the migration. > Perhaps, you model it like a collection of actions. So.. you POST to /vms/999/rebootRequests which gives you back a resource which looks like (pardon the xml) SOME DATE SOME DUDE SOME STATUS This way, the request itself is a resource. Assuming infinate DB Space, you keep it for the life of the machine. Or.. a post to reboot could redirect you to /vms/999/actions Which gives you the same basic object reboot SOME DATE SOME DUDE SOME STATUS > Now it's the lifecycle of the temporary resource represented by this URI > that seems to be potentially problematic. While the async operation is > still in flight, there's no problem. However the question is how long > _after_ the operation has completed should we maintain this resource so > that the client can eventually determine the outcome? We've no guarantee > that the client will poll regularly, so say we impose some arbitrary > expiry, maybe 10 minutes after the task has completed. But even for that > limited time we seem to be breaking one of the fundamental Fielding > commandments, the one that demands session state is kept entirely on the > client side. After the task completes, this URI no longer represents a > resource per se, rather we'd just be keeping it around for a while to > support our conversation with the client. > > So another more extreme approach would be to limit the client to: > > (a) checking whether the async operation is still being processed, so > that the status URI is only valid until the task completes, > > (b) inferring from the current state of the VM whether the task may have > succeeded or failed, for example the client gets a big hint that its > stop operation has failed if the task has completed but the VM state > hasn't transitioned to DOWN (or course there's a race here, as the VM > may simply have been restarted in the meantime by another agent), > > and, > > (c) getting a indirect indication of the failure reason by scanning an > event/audit log. I am also fine with querying the state of the object.. but I bet you have a need for a log anyways. -- bk From bmcwhirt at redhat.com Tue Apr 20 15:13:35 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Tue, 20 Apr 2010 11:13:35 -0400 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <4BCDA153.5090401@redhat.com> References: <1271704843.3965.20.camel@quark> <4BCDA153.5090401@redhat.com> Message-ID: > This way, the request itself is a resource. Assuming infinate DB > Space, you keep it for the life of the machine. And suddenly we have a little more auditability. Who rebooted the DB at 3pm? Dave did! It also would allow for some more logic to be applied, in the case someone screws up a script and sends 200 reboot requests in a short period. The first is acknowledged, perhaps the other 199 are marked INVALID because the machine is already REBOOTING. -Bob From bburke at redhat.com Tue Apr 20 15:19:40 2010 From: bburke at redhat.com (Bill Burke) Date: Tue, 20 Apr 2010 11:19:40 -0400 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <1271768396.2830.51.camel@blaa> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <1271439881.15762.37.camel@localhost> <1271768396.2830.51.camel@blaa> Message-ID: <4BCDC60C.1040708@redhat.com> Mark McLoughlin wrote: >> Atom-style links are nice for references to URL's that are not some sort >> of object in the system, > > What are they, then? By giving them a URI, we're modelling actions as > objects too :-) > >> but they're not a particularly nice way to handle object references. > > Bill makes the case for Atom links in his book and I agree it makes some > sense. But I actually don't particularly care - we're designing a new > API and trying to stick with the 'consensus approach' rather than going > and re-inventing the wheel. > To me, it just feels wrong to have to do a diff on a posted representation to figure out what exact complex logic that has to be triggered. What I'm starting to do lately is always ask the question, how would I model something in a browser-based application? For shutdown of a VM, would I really have one monster html form that contained all the mutable bits of state of the VM and submit it all with one post? No. I'd break things up into smaller HTML forums embedded in a bigger HTML document. BTW, I'm not sure what you mean by 'consensus approach'. IMO, REST + Web Services (or in other words non-browser-based REST) is a fairly new area. I guess what I'm saying is that because things are still relatively new, different things should be tried to improve an API rather than worrying about a 'consensus approach'. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From markmc at redhat.com Tue Apr 20 15:53:41 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 20 Apr 2010 16:53:41 +0100 Subject: [rest-practices] Atom as a generic container? [was Re: Media types] In-Reply-To: <4BCDC60C.1040708@redhat.com> References: <1271332461.22267.45.camel@blaa> <4BC70601.1020005@redhat.com> <4BC70A49.6040104@redhat.com> <1271409769.7677.46.camel@blaa> <4BC852B8.9010101@redhat.com> <1271439881.15762.37.camel@localhost> <1271768396.2830.51.camel@blaa> <4BCDC60C.1040708@redhat.com> Message-ID: <1271778821.1633.18.camel@blaa> On Tue, 2010-04-20 at 11:19 -0400, Bill Burke wrote: > > Mark McLoughlin wrote: > >> Atom-style links are nice for references to URL's that are not some sort > >> of object in the system, > > > > What are they, then? By giving them a URI, we're modelling actions as > > objects too :-) > > > >> but they're not a particularly nice way to handle object references. > > > > Bill makes the case for Atom links in his book and I agree it makes some > > sense. But I actually don't particularly care - we're designing a new > > API and trying to stick with the 'consensus approach' rather than going > > and re-inventing the wheel. > > > > To me, it just feels wrong to have to do a diff on a posted > representation to figure out what exact complex logic that has to be > triggered. What I'm starting to do lately is always ask the question, > how would I model something in a browser-based application? For > shutdown of a VM, would I really have one monster html form that > contained all the mutable bits of state of the VM and submit it all with > one post? No. I'd break things up into smaller HTML forums embedded in > a bigger HTML document. I'm confused ... are we still talking about: versus Your point sounds more relevant to the async operations thread, no? > BTW, I'm not sure what you mean by 'consensus approach'. IMO, REST + > Web Services (or in other words non-browser-based REST) is a fairly new > area. I guess what I'm saying is that because things are still > relatively new, different things should be tried to improve an API > rather than worrying about a 'consensus approach'. I agree, up to a point - we should definitely feel free to try and approve on approaches taken by others, rather than blindly follow them But, given a relatively arbitrary choice between two equally good approaches, I'd prefer to go along with a rough consensus We don't want the Deltacloud and RHEV-M APIs (which are closely related) to be look arbitrarily different for no other real reason than e.g. whether they were implemented using ruby or RESTeasy There is value in *some* consistency in the design of our RESTful APIs within the same product group (if not the whole company) and AFAICT, that is one of the reasons we set up this list It'd also be nice if not everyone who wanted to add a RESTful API had to go through this fairly tortuous discussion of the different approaches :-) Cheers, Mark. From eglynn at redhat.com Tue Apr 20 18:05:04 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Tue, 20 Apr 2010 19:05:04 +0100 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <4BCDA153.5090401@redhat.com> References: <1271704843.3965.20.camel@quark> <4BCDA153.5090401@redhat.com> Message-ID: <1271786704.3965.176.camel@quark> Thanks for the feedback, folks. So I've been chewing away on our requirements around minimal updates to search queries and also the asynchronous actions discussed on this thread. I'm tending towards a design whereby we maintain a sort of three-level cache of VM-related representations: 1. The VM collection, which represents our best state of knowledge of the current status of each VM. This is used to populate the response to GET /vms?query=... style operations. 2. A list of completed VM state changes, only the most recent for each VM. The length of this list is bounded by the VM collection size, but its also aggressively reaped, so in general it would be much smaller. The idea is to return a link to the next free slot in this list along with the result of any queries evaluated over the entire VM collection in #1, so that a client can periodically refresh its query result set without re-evaluating the entire query. The client effectively polls on the tail of the update list, only seeing those state changes that occured _after_ its initial GET. A retrieval on a reaped VM state-change resource is simply 301-redirected back to the main collection. 3. A potentially larger queue of pending or in-progress actions, of which there may be more than one outstanding per VM (in the case of a sequence of actions being submitted in quick succession). A reference to a resource representing the corresponding action is returned with the initial 202 Accepted response to the POST on an action URI. Once the task is completed, whether it succeeded or failed, this resource becomes part of the audit trail and is effectively persisted, presumably with a longer lifespan than any reasonable client. So #2 allows client to efficiently refresh their queries without any dependence on special handling of If-Modified-Since, whereas #3 skates around the statefulness prohibition. Cheers, Eoghan On Tue, 2010-04-20 at 08:42 -0400, Bryan Kearney wrote: > On 04/19/2010 03:20 PM, Eoghan Glynn wrote: > > > > Hi Folks, > > > > I wanted to get your feeling on the question of breaking statelessness > > when asynchronous operations are used, in particular in terms of the > > protocol used to check the outcome of the deferred task. > > > > So say we need to model a potentially long-lived operation, such as > > migrating a VM. To avoid tying up a connection for the duration, the > > server could respond to the "POST /vms/999/reboot" request with a 202 > > Accepted, along with a unique URI to be used subsequently to check on > > the status of the migration. > > > > Perhaps, you model it like a collection of actions. So.. you POST to > > /vms/999/rebootRequests > > which gives you back a resource which looks like (pardon the xml) > > > SOME DATE > SOME DUDE > SOME STATUS > > > This way, the request itself is a resource. Assuming infinate DB Space, > you keep it for the life of the machine. > > Or.. a post to reboot could redirect you to /vms/999/actions > > Which gives you the same basic object > > > reboot > SOME DATE > SOME DUDE > SOME STATUS > > > > > Now it's the lifecycle of the temporary resource represented by this URI > > that seems to be potentially problematic. While the async operation is > > still in flight, there's no problem. However the question is how long > > _after_ the operation has completed should we maintain this resource so > > that the client can eventually determine the outcome? We've no guarantee > > that the client will poll regularly, so say we impose some arbitrary > > expiry, maybe 10 minutes after the task has completed. But even for that > > limited time we seem to be breaking one of the fundamental Fielding > > commandments, the one that demands session state is kept entirely on the > > client side. After the task completes, this URI no longer represents a > > resource per se, rather we'd just be keeping it around for a while to > > support our conversation with the client. > > > > So another more extreme approach would be to limit the client to: > > > > (a) checking whether the async operation is still being processed, so > > that the status URI is only valid until the task completes, > > > > (b) inferring from the current state of the VM whether the task may have > > succeeded or failed, for example the client gets a big hint that its > > stop operation has failed if the task has completed but the VM state > > hasn't transitioned to DOWN (or course there's a race here, as the VM > > may simply have been restarted in the meantime by another agent), > > > > and, > > > > (c) getting a indirect indication of the failure reason by scanning an > > event/audit log. > > > I am also fine with querying the state of the object.. but I bet you > have a need for a log anyways. > > -- bk From markmc at redhat.com Tue Apr 20 19:32:05 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 20 Apr 2010 20:32:05 +0100 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1271773334.3965.84.camel@quark> References: <1271773334.3965.84.camel@quark> Message-ID: <1271791925.1633.34.camel@blaa> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: > Folks, > > A REST design question ... suppose we're using the same representation > in a number of different contexts: > > 1. to capture client input to resource creation (i.e. the payload in the > POST /collection request) > > 2. to encode a state change initiated by the client (i.e. the payload > for the PUT /collection/id request) > > 3. to represent the complete resource state sent back to the client > (i.e. response to GET /collection/id) > > Say the representations used in cases #1 and #2 are a proper subset of > #3, because some of the fields must be computed, or have fixed > defaults/initial values. So the question is, how do we enforce this > constraint? > > We could define separate types to ensure that only those fields that > really can be set by the client are used in the POST and PUT, and then > enforce via schema validation or whatever. > > Or is best to be tolerant and just silently discard any read-only fields > specified in the first two cases? (We discussed already, but for the benefit of discussion here) For simplicity sake, I think it makes sense to stick with the same representation. Rather than silently discard read-only fields, though, I'd prefer us to return an error. That way the semantics are clear. It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't seem to be. Cheers, Mark. From bkearney at redhat.com Tue Apr 20 19:41:04 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Tue, 20 Apr 2010 15:41:04 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1271791925.1633.34.camel@blaa> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> Message-ID: <4BCE0350.4010701@redhat.com> On 04/20/2010 03:32 PM, Mark McLoughlin wrote: > On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: > >> Folks, >> >> A REST design question ... suppose we're using the same representation >> in a number of different contexts: >> >> 1. to capture client input to resource creation (i.e. the payload in the >> POST /collection request) >> >> 2. to encode a state change initiated by the client (i.e. the payload >> for the PUT /collection/id request) >> >> 3. to represent the complete resource state sent back to the client >> (i.e. response to GET /collection/id) >> >> Say the representations used in cases #1 and #2 are a proper subset of >> #3, because some of the fields must be computed, or have fixed >> defaults/initial values. So the question is, how do we enforce this >> constraint? >> >> We could define separate types to ensure that only those fields that >> really can be set by the client are used in the POST and PUT, and then >> enforce via schema validation or whatever. >> >> Or is best to be tolerant and just silently discard any read-only fields >> specified in the first two cases? > > (We discussed already, but for the benefit of discussion here) > > For simplicity sake, I think it makes sense to stick with the same > representation. > > Rather than silently discard read-only fields, though, I'd prefer us to > return an error. That way the semantics are clear. > > It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't > seem to be. This is one reason where I think a WADL type tool would be nice. I do not want to use WADL to define my services, but I would like some description of them to give to clients to say "If you do this, it will work". The argument of not using wadl because of HATEOAS does not fly to well.. since we should be able to encode the link names. As to your solution, I would think with versioning that you would want to fail silently. If the client sends more data to a back-reved server it may be nice to have it still work. -- bk From bburke at redhat.com Wed Apr 21 13:20:57 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 21 Apr 2010 09:20:57 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCE0350.4010701@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> Message-ID: <4BCEFBB9.7010509@redhat.com> Bryan Kearney wrote: > On 04/20/2010 03:32 PM, Mark McLoughlin wrote: >> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: >> >>> Folks, >>> >>> A REST design question ... suppose we're using the same representation >>> in a number of different contexts: >>> >>> 1. to capture client input to resource creation (i.e. the payload in the >>> POST /collection request) >>> >>> 2. to encode a state change initiated by the client (i.e. the payload >>> for the PUT /collection/id request) >>> >>> 3. to represent the complete resource state sent back to the client >>> (i.e. response to GET /collection/id) >>> >>> Say the representations used in cases #1 and #2 are a proper subset of >>> #3, because some of the fields must be computed, or have fixed >>> defaults/initial values. So the question is, how do we enforce this >>> constraint? >>> >>> We could define separate types to ensure that only those fields that >>> really can be set by the client are used in the POST and PUT, and then >>> enforce via schema validation or whatever. >>> >>> Or is best to be tolerant and just silently discard any read-only fields >>> specified in the first two cases? >> >> (We discussed already, but for the benefit of discussion here) >> >> For simplicity sake, I think it makes sense to stick with the same >> representation. >> >> Rather than silently discard read-only fields, though, I'd prefer us to >> return an error. That way the semantics are clear. >> >> It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't >> seem to be. > > > This is one reason where I think a WADL type tool would be nice. I do > not want to use WADL to define my services, but I would like some > description of them to give to clients to say "If you do this, it will > work". The argument of not using wadl because of HATEOAS does not fly to > well.. since we should be able to encode the link names. > Or, you could just write a document that said "If you do this, it will work...", put it on a searchable wiki. Reference the page within schema URLs and link relationship urls, etc. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bkearney at redhat.com Wed Apr 21 15:05:49 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Wed, 21 Apr 2010 11:05:49 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCEFBB9.7010509@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> Message-ID: <4BCF144D.9020807@redhat.com> On 04/21/2010 09:20 AM, Bill Burke wrote: > > > Bryan Kearney wrote: >> On 04/20/2010 03:32 PM, Mark McLoughlin wrote: >>> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: >>> >>>> Folks, >>>> >>>> A REST design question ... suppose we're using the same representation >>>> in a number of different contexts: >>>> >>>> 1. to capture client input to resource creation (i.e. the payload in >>>> the >>>> POST /collection request) >>>> >>>> 2. to encode a state change initiated by the client (i.e. the payload >>>> for the PUT /collection/id request) >>>> >>>> 3. to represent the complete resource state sent back to the client >>>> (i.e. response to GET /collection/id) >>>> >>>> Say the representations used in cases #1 and #2 are a proper subset of >>>> #3, because some of the fields must be computed, or have fixed >>>> defaults/initial values. So the question is, how do we enforce this >>>> constraint? >>>> >>>> We could define separate types to ensure that only those fields that >>>> really can be set by the client are used in the POST and PUT, and then >>>> enforce via schema validation or whatever. >>>> >>>> Or is best to be tolerant and just silently discard any read-only >>>> fields >>>> specified in the first two cases? >>> >>> (We discussed already, but for the benefit of discussion here) >>> >>> For simplicity sake, I think it makes sense to stick with the same >>> representation. >>> >>> Rather than silently discard read-only fields, though, I'd prefer us to >>> return an error. That way the semantics are clear. >>> >>> It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't >>> seem to be. >> >> >> This is one reason where I think a WADL type tool would be nice. I do >> not want to use WADL to define my services, but I would like some >> description of them to give to clients to say "If you do this, it will >> work". The argument of not using wadl because of HATEOAS does not fly >> to well.. since we should be able to encode the link names. >> > > Or, you could just write a document that said "If you do this, it will > work...", put it on a searchable wiki. Reference the page within schema > URLs and link relationship urls, etc. > > In my experience, developers will forget to update it. I would prefer to auto generate it off of the code. -- bk From bburke at redhat.com Wed Apr 21 15:14:11 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 21 Apr 2010 11:14:11 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCF144D.9020807@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> Message-ID: <4BCF1643.6070604@redhat.com> Bryan Kearney wrote: > On 04/21/2010 09:20 AM, Bill Burke wrote: >> >> >> Bryan Kearney wrote: >>> On 04/20/2010 03:32 PM, Mark McLoughlin wrote: >>>> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: >>>> >>>>> Folks, >>>>> >>>>> A REST design question ... suppose we're using the same representation >>>>> in a number of different contexts: >>>>> >>>>> 1. to capture client input to resource creation (i.e. the payload in >>>>> the >>>>> POST /collection request) >>>>> >>>>> 2. to encode a state change initiated by the client (i.e. the payload >>>>> for the PUT /collection/id request) >>>>> >>>>> 3. to represent the complete resource state sent back to the client >>>>> (i.e. response to GET /collection/id) >>>>> >>>>> Say the representations used in cases #1 and #2 are a proper subset of >>>>> #3, because some of the fields must be computed, or have fixed >>>>> defaults/initial values. So the question is, how do we enforce this >>>>> constraint? >>>>> >>>>> We could define separate types to ensure that only those fields that >>>>> really can be set by the client are used in the POST and PUT, and then >>>>> enforce via schema validation or whatever. >>>>> >>>>> Or is best to be tolerant and just silently discard any read-only >>>>> fields >>>>> specified in the first two cases? >>>> >>>> (We discussed already, but for the benefit of discussion here) >>>> >>>> For simplicity sake, I think it makes sense to stick with the same >>>> representation. >>>> >>>> Rather than silently discard read-only fields, though, I'd prefer us to >>>> return an error. That way the semantics are clear. >>>> >>>> It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't >>>> seem to be. >>> >>> >>> This is one reason where I think a WADL type tool would be nice. I do >>> not want to use WADL to define my services, but I would like some >>> description of them to give to clients to say "If you do this, it will >>> work". The argument of not using wadl because of HATEOAS does not fly >>> to well.. since we should be able to encode the link names. >>> >> >> Or, you could just write a document that said "If you do this, it will >> work...", put it on a searchable wiki. Reference the page within schema >> URLs and link relationship urls, etc. >> >> > In my experience, developers will forget to update it. I would prefer to > auto generate it off of the code. > Good point. A resteasy committer has written a jaxrs-javadoc generator. Of course this wouldn't work very well with non-java implementations. Jersey has nice support for WADL. Wouldn't be hurt if you decided to move to it because of WADL. I just don't have the time or will to get into any WADL development/support. While WADL does support the concept of linking and opaque URLs, it doesn't contrain itself. I worry that with WADL you'll get a tighter coupling between client-server that isn't desired. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Wed Apr 21 15:17:52 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 21 Apr 2010 11:17:52 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCF1643.6070604@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> Message-ID: <4BCF1720.4020400@redhat.com> Bill Burke wrote: > > > Bryan Kearney wrote: >> On 04/21/2010 09:20 AM, Bill Burke wrote: >>> >>> >>> Bryan Kearney wrote: >>>> On 04/20/2010 03:32 PM, Mark McLoughlin wrote: >>>>> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: >>>>> >>>>>> Folks, >>>>>> >>>>>> A REST design question ... suppose we're using the same >>>>>> representation >>>>>> in a number of different contexts: >>>>>> >>>>>> 1. to capture client input to resource creation (i.e. the payload in >>>>>> the >>>>>> POST /collection request) >>>>>> >>>>>> 2. to encode a state change initiated by the client (i.e. the payload >>>>>> for the PUT /collection/id request) >>>>>> >>>>>> 3. to represent the complete resource state sent back to the client >>>>>> (i.e. response to GET /collection/id) >>>>>> >>>>>> Say the representations used in cases #1 and #2 are a proper >>>>>> subset of >>>>>> #3, because some of the fields must be computed, or have fixed >>>>>> defaults/initial values. So the question is, how do we enforce this >>>>>> constraint? >>>>>> >>>>>> We could define separate types to ensure that only those fields that >>>>>> really can be set by the client are used in the POST and PUT, and >>>>>> then >>>>>> enforce via schema validation or whatever. >>>>>> >>>>>> Or is best to be tolerant and just silently discard any read-only >>>>>> fields >>>>>> specified in the first two cases? >>>>> >>>>> (We discussed already, but for the benefit of discussion here) >>>>> >>>>> For simplicity sake, I think it makes sense to stick with the same >>>>> representation. >>>>> >>>>> Rather than silently discard read-only fields, though, I'd prefer >>>>> us to >>>>> return an error. That way the semantics are clear. >>>>> >>>>> It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't >>>>> seem to be. >>>> >>>> >>>> This is one reason where I think a WADL type tool would be nice. I do >>>> not want to use WADL to define my services, but I would like some >>>> description of them to give to clients to say "If you do this, it will >>>> work". The argument of not using wadl because of HATEOAS does not fly >>>> to well.. since we should be able to encode the link names. >>>> >>> >>> Or, you could just write a document that said "If you do this, it will >>> work...", put it on a searchable wiki. Reference the page within schema >>> URLs and link relationship urls, etc. >>> >>> >> In my experience, developers will forget to update it. I would prefer >> to auto generate it off of the code. >> > > Good point. A resteasy committer has written a jaxrs-javadoc generator. > Of course this wouldn't work very well with non-java implementations. > Jersey has nice support for WADL. Wouldn't be hurt if you decided to > move to it because of WADL. I just don't have the time or will to get > into any WADL development/support. > > While WADL does support the concept of linking and opaque URLs, it > doesn't contrain itself. I worry that with WADL you'll get a tighter > coupling between client-server that isn't desired. > BTW, I'm not sure Jersey's WADL support is gonna support automated link introspection and you'll still have the "forgetting to update" problem. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bkearney at redhat.com Wed Apr 21 15:47:49 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Wed, 21 Apr 2010 11:47:49 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCF1720.4020400@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> Message-ID: <4BCF1E25.6060004@redhat.com> On 04/21/2010 11:17 AM, Bill Burke wrote: > > > Bill Burke wrote: >>> >> >> Good point. A resteasy committer has written a jaxrs-javadoc >> generator. Of course this wouldn't work very well with non-java >> implementations. Jersey has nice support for WADL. Wouldn't be hurt if >> you decided to move to it because of WADL. I just don't have the time >> or will to get into any WADL development/support. >> Naw.. I like using our own stuff where we can. I will look at the javadoc stuff. Would you be opposed to a WADL contribution? >> While WADL does support the concept of linking and opaque URLs, it >> doesn't contrain itself. I worry that with WADL you'll get a tighter >> coupling between client-server that isn't desired. >> > > BTW, I'm not sure Jersey's WADL support is gonna support automated link > introspection and you'll still have the "forgetting to update" problem. > I would hope once there is a standardized way to decorating your objects with possible links, that a tool could say: "Here are all the links which could exist" Although for any specific resource, they may not. -- bk From mlittle at redhat.com Fri Apr 23 12:30:07 2010 From: mlittle at redhat.com (Mark Little) Date: Fri, 23 Apr 2010 13:30:07 +0100 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BCF1E25.6060004@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> Message-ID: The debate as to whether or not to use WADL isn't tied to HATEOS, which as you know is only one aspect of REST: the reasons not to use it go much deeper than that. I assume you've checked out various resources like ... http://www.25hoursaday.com/weblog/2007/06/04/WhatsWrongWithWADL.aspx http://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl http://www.markbaker.ca/blog/2007/05/rest-wadl-forest-trees/comment-page-1/ http://www.innoq.com/blog/st/2007/06/wadl_just_a_hypermedia_format.html http://www.tbray.org/ongoing/When/200x/2007/05/28/REST http://www.mnot.net/blog/2008/01/21/wadl_watching http://www.infoq.com/news/2007/03/WADL And the fact it's a W3C submission (aka Note) doesn't mean it'll ever become a standard. http://www.w3.org/Submission/wadl/ Mark. On 21 Apr 2010, at 16:47, Bryan Kearney wrote: > On 04/21/2010 11:17 AM, Bill Burke wrote: >> >> >> Bill Burke wrote: >>>> >>> >>> Good point. A resteasy committer has written a jaxrs-javadoc >>> generator. Of course this wouldn't work very well with non-java >>> implementations. Jersey has nice support for WADL. Wouldn't be >>> hurt if >>> you decided to move to it because of WADL. I just don't have the >>> time >>> or will to get into any WADL development/support. >>> > > Naw.. I like using our own stuff where we can. I will look at the > javadoc stuff. Would you be opposed to a WADL contribution? > >>> While WADL does support the concept of linking and opaque URLs, it >>> doesn't contrain itself. I worry that with WADL you'll get a tighter >>> coupling between client-server that isn't desired. >>> >> >> BTW, I'm not sure Jersey's WADL support is gonna support automated >> link >> introspection and you'll still have the "forgetting to update" >> problem. >> > > I would hope once there is a standardized way to decorating your > objects with possible links, that a tool could say: > > "Here are all the links which could exist" > > Although for any specific resource, they may not. > > -- bk > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices --- Mark Little mlittle at redhat.com JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland). From bkearney at redhat.com Fri Apr 23 12:54:19 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Fri, 23 Apr 2010 08:54:19 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> Message-ID: <4BD1987B.6090003@redhat.com> On 04/23/2010 08:30 AM, Mark Little wrote: > The debate as to whether or not to use WADL isn't tied to HATEOS, which > as you know is only one aspect of REST: the reasons not to use it go > much deeper than that. I assume you've checked out various resources > like ... Well.. that is the common refrain. If you are describing the URLs, you _must_ not be using the links, and therefore you are too tightly coupled to the server. I find it interesting that the on ramp to rest is "it is simpler", which it is when you go the bookmark approach, and send http requests to known resource locations. If I was asked to write a client against "ThatKoolRestAPI" then either: 1) The developers had better documented every resource, and every action link which is possible from each link or 2) I have to execute each path manually (or with loggin) to see what I can do next. Since I tend not to trust developers to always update the documentation, it seems like an automated means to do (1) would be valuable to the API writers as well as documenters. Note, I am not advocation IDL driven development. Develop the code, generate the IDL. > > http://www.25hoursaday.com/weblog/2007/06/04/WhatsWrongWithWADL.aspx > http://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl > > http://www.markbaker.ca/blog/2007/05/rest-wadl-forest-trees/comment-page-1/ > http://www.innoq.com/blog/st/2007/06/wadl_just_a_hypermedia_format.html > http://www.tbray.org/ongoing/When/200x/2007/05/28/REST > http://www.mnot.net/blog/2008/01/21/wadl_watching > http://www.infoq.com/news/2007/03/WADL Some of the these are against it, but much of the haters are in the comments. The best valuable comments are from the fist link which talk about the issues of using XSD as the means to validate. I think these are valid. I would rather see the discussion be around how to make a good descriptor syntax, but it seems to be focused on "why would you ever want to describe your API?" -- bk From bburke at redhat.com Fri Apr 23 13:24:45 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 23 Apr 2010 09:24:45 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BD1987B.6090003@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> Message-ID: <4BD19F9D.6090109@redhat.com> Bryan Kearney wrote: > On 04/23/2010 08:30 AM, Mark Little wrote: >> The debate as to whether or not to use WADL isn't tied to HATEOS, which >> as you know is only one aspect of REST: the reasons not to use it go >> much deeper than that. I assume you've checked out various resources >> like ... > > Well.. that is the common refrain. If you are describing the URLs, you > _must_ not be using the links, and therefore you are too tightly coupled > to the server. > > I find it interesting that the on ramp to rest is "it is simpler", which > it is when you go the bookmark approach, and send http requests to known > resource locations. If I was asked to write a client against > "ThatKoolRestAPI" then either: > > 1) The developers had better documented every resource, and every action > link which is possible from each link > > or > > 2) I have to execute each path manually (or with loggin) to see what I > can do next. > > Since I tend not to trust developers to always update the documentation, > it seems like an automated means to do (1) would be valuable to the API > writers as well as documenters. Note, I am not advocation IDL driven > development. Develop the code, generate the IDL. > I think the difference is that, if documentation is out of sync, that the protocol can be hacked by looking at returned responses and data. > >> >> http://www.25hoursaday.com/weblog/2007/06/04/WhatsWrongWithWADL.aspx >> http://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl >> >> >> http://www.markbaker.ca/blog/2007/05/rest-wadl-forest-trees/comment-page-1/ >> >> http://www.innoq.com/blog/st/2007/06/wadl_just_a_hypermedia_format.html >> http://www.tbray.org/ongoing/When/200x/2007/05/28/REST >> http://www.mnot.net/blog/2008/01/21/wadl_watching >> http://www.infoq.com/news/2007/03/WADL > > Some of the these are against it, but much of the haters are in the > comments. The best valuable comments are from the fist link which talk > about the issues of using XSD as the means to validate. I think these > are valid. I would rather see the discussion be around how to make a > good descriptor syntax, but it seems to be focused on "why would you > ever want to describe your API?" > Well, afaik, there is no tool that can scan both code and XML schema to come up with a WADL or similar document that describes application flow. So, you're still gonna have the dependency on the developer to update the WADL document or human documentation. I think this blurb from one of the blogs describes what I mean perfectly: "And an IDL is simply a list of API signatures. It doesn't describe expected message exchange patterns, required authentication methods, message traffic limits, quality of service guarantees, or even pre and post conditions for the various method calls. You usually find this information in the documentation and/or in the actual business contract one signed with the Web service provider. A WADL document for the REST Web service will not change this fact." -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From pmyers at redhat.com Fri Apr 23 14:32:44 2010 From: pmyers at redhat.com (Perry Myers) Date: Fri, 23 Apr 2010 10:32:44 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BC609F8.6020502@redhat.com> References: <4BC609F8.6020502@redhat.com> Message-ID: <4BD1AF8C.1060106@redhat.com> On 04/14/2010 02:31 PM, Perry Myers wrote: > I was asked to create and moderate this list with the following purpose in > mind... > > We've got a lot of components in use across Red Hat and the upstream > communities that utilize interfaces like QMF and REST. It would be a good > thing to have all of the different communities that are producing APIs > communicate together to make sure that these API definitions are > consistent in both style and usage. > > This mailing list will focus specifically on best practices for using > REST, since we will be providing either native REST interfaces for many of > our APIs or layering REST on top of other interfaces like QMF. > > One other side project is to create a generic QMF<->REST binding in Ruby. > Bob M. and Ted R. are leading this and can comment further. > > Welcome to the list, and if you feel there are others that should > participate please feel free to invite them. This is an open and external > forum, as we want community observation and involvement as we develop > externally consumable APIs using REST. > > To start with, it might be useful for the existing folks on list that are > already creating (have created) REST APIs to provide a little background > context about their specific APIs and links to documentation on them. So far, very productive discussions I think. It's good to have all the experts collaborating in one place :) One thing that I wanted to mention that falls into what the purpose of this list is... For cloud related efforts, we want to make sure that all of our usages of REST are consistent wrt style/best practices. Ideally, it would be best if all Red Hat REST usage is on the same page. But barring that, the cloud usage should at least be consistent. So bburke's REST pages are certainly a good starting poing wrt style/usage. But Mark M. will also be maintaining a separate wiki page (he'll provide the link) that is specific to cloud usage of REST. Hopefully it won't duplicate all of the good work that bburke has done, but instead will just point out style differences between his pages and what cloud folks agree on. It will be expected that all cloud developers will conform to the style as agreed upon in Mark's wiki page. Thanks, Perry From bburke at redhat.com Fri Apr 23 15:09:48 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 23 Apr 2010 11:09:48 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BD1AF8C.1060106@redhat.com> References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> Message-ID: <4BD1B83C.5080607@redhat.com> Perry Myers wrote: > On 04/14/2010 02:31 PM, Perry Myers wrote: >> I was asked to create and moderate this list with the following purpose in >> mind... >> >> We've got a lot of components in use across Red Hat and the upstream >> communities that utilize interfaces like QMF and REST. It would be a good >> thing to have all of the different communities that are producing APIs >> communicate together to make sure that these API definitions are >> consistent in both style and usage. >> >> This mailing list will focus specifically on best practices for using >> REST, since we will be providing either native REST interfaces for many of >> our APIs or layering REST on top of other interfaces like QMF. >> >> One other side project is to create a generic QMF<->REST binding in Ruby. >> Bob M. and Ted R. are leading this and can comment further. >> >> Welcome to the list, and if you feel there are others that should >> participate please feel free to invite them. This is an open and external >> forum, as we want community observation and involvement as we develop >> externally consumable APIs using REST. >> >> To start with, it might be useful for the existing folks on list that are >> already creating (have created) REST APIs to provide a little background >> context about their specific APIs and links to documentation on them. > > So far, very productive discussions I think. It's good to have all the > experts collaborating in one place :) > > One thing that I wanted to mention that falls into what the purpose of > this list is... > > For cloud related efforts, we want to make sure that all of our usages of > REST are consistent wrt style/best practices. Ideally, it would be best > if all Red Hat REST usage is on the same page. But barring that, the > cloud usage should at least be consistent. > > So bburke's REST pages are certainly a good starting poing wrt > style/usage. But Mark M. will also be maintaining a separate wiki page > (he'll provide the link) that is specific to cloud usage of REST. > Hopefully it won't duplicate all of the good work that bburke has done, > but instead will just point out style differences between his pages and > what cloud folks agree on. > Ok, then, I guess I don't have to do any more work then on the wiki page I created. Less work == good. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From lutter at redhat.com Fri Apr 23 15:11:41 2010 From: lutter at redhat.com (David Lutterkort) Date: Fri, 23 Apr 2010 17:11:41 +0200 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1271791925.1633.34.camel@blaa> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> Message-ID: <1272035501.5275.26.camel@localhost> On Tue, 2010-04-20 at 20:32 +0100, Mark McLoughlin wrote: > On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote: > > > Folks, > > > > A REST design question ... suppose we're using the same representation > > in a number of different contexts: > > > > 1. to capture client input to resource creation (i.e. the payload in the > > POST /collection request) > > > > 2. to encode a state change initiated by the client (i.e. the payload > > for the PUT /collection/id request) > > > > 3. to represent the complete resource state sent back to the client > > (i.e. response to GET /collection/id) > > > > Say the representations used in cases #1 and #2 are a proper subset of > > #3, because some of the fields must be computed, or have fixed > > defaults/initial values. So the question is, how do we enforce this > > constraint? > > > > We could define separate types to ensure that only those fields that > > really can be set by the client are used in the POST and PUT, and then > > enforce via schema validation or whatever. > > > > Or is best to be tolerant and just silently discard any read-only fields > > specified in the first two cases? > > (We discussed already, but for the benefit of discussion here) > > For simplicity sake, I think it makes sense to stick with the same > representation. > > Rather than silently discard read-only fields, though, I'd prefer us to > return an error. That way the semantics are clear. That's kinda the opposite of what we expect from clients - for those, we want them to pick out what they know about, and ignore the rest. As long as what they send is unambiguous, I don't see the harm in ignoring read-only fields. This whole discussion is really caused by the paucity of API/schema documentation tools. In an ideal world, we could have one schema for each object, and indicate which parts of the schema are relevant for what operations. David From lutter at redhat.com Fri Apr 23 15:20:50 2010 From: lutter at redhat.com (David Lutterkort) Date: Fri, 23 Apr 2010 17:20:50 +0200 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BD19F9D.6090109@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> <4BD19F9D.6090109@redhat.com> Message-ID: <1272036050.5275.31.camel@localhost> On Fri, 2010-04-23 at 09:24 -0400, Bill Burke wrote: > I think this blurb from one of the blogs describes what I mean perfectly: > > "And an IDL is simply a list of API signatures. It doesn't describe > expected message exchange patterns, required authentication methods, > message traffic limits, quality of service guarantees, or even pre and > post conditions for the various method calls. You usually find this > information in the documentation and/or in the actual business contract > one signed with the Web service provider. A WADL document for the REST > Web service will not change this fact." Nicely put. I assume that implies that API docs should be in POE (plain old English) - I am all for that, since I really doubt that any formal API spec will ever be up-to-date with the code or get real use by clients. In theory (as in: if they weren't so annoying to write, I'd write them), RelaxNG schemas for XML returned are useful mostly for testing the API against inadvertant schema changes. On a tangent, for Deltacloud core, we have a simple system that generates what parameters are accepted for each operation from the code. I wouldn't call that API documentation in any formal sense, more a gentle reminder to the API user of what's available and how. David From bmcwhirt at redhat.com Fri Apr 23 15:51:19 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Fri, 23 Apr 2010 11:51:19 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1272035501.5275.26.camel@localhost> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <1272035501.5275.26.camel@localhost> Message-ID: <246181ED-8253-4DC1-B709-51B2FEF42FC2@redhat.com> >> Rather than silently discard read-only fields, though, I'd prefer >> us to >> return an error. That way the semantics are clear. > > That's kinda the opposite of what we expect from clients - for > those, we > want them to pick out what they know about, and ignore the rest. As > long > as what they send is unambiguous, I don't see the harm in ignoring > read-only fields. In fact, one usage is to fetch XML, simply modify that document (using xpath) and returning it, in its entirety, back to the server. There, I'd hope that server really only considers fields that've honestly *changed*. If I replace a readonly value with another different value, I'd expect an error (Sorry, can't modify a read-only field), but otherwise, I'd expect it to notice what really got changed in the read/write attributes. With REST, client and server are exchanging their views of the world. The client's not instructing the server to change particular fields. More "Hey, I now consider this object to look like this". That can either be compatible, or incompatible (ie, changes to read- only fields) with the server's policy. -Bob From markmc at redhat.com Fri Apr 23 16:02:16 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Fri, 23 Apr 2010 17:02:16 +0100 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <246181ED-8253-4DC1-B709-51B2FEF42FC2@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <1272035501.5275.26.camel@localhost> <246181ED-8253-4DC1-B709-51B2FEF42FC2@redhat.com> Message-ID: <1272038536.3229.215.camel@blaa> On Fri, 2010-04-23 at 11:51 -0400, Bob McWhirter wrote: > >> Rather than silently discard read-only fields, though, I'd prefer > >> us to > >> return an error. That way the semantics are clear. > > > > That's kinda the opposite of what we expect from clients - for > > those, we > > want them to pick out what they know about, and ignore the rest. As > > long > > as what they send is unambiguous, I don't see the harm in ignoring > > read-only fields. > > In fact, one usage is to fetch XML, simply modify that document (using > xpath) and returning it, in its entirety, back to the server. Yeah, that's got to be a common case. > There, I'd hope that server really only considers fields that've > honestly *changed*. If I replace a readonly value with another > different value, I'd expect an error (Sorry, can't modify a read-only > field), but otherwise, I'd expect it to notice what really got changed > in the read/write attributes. I like it, except for read-only fields that change a lot - e.g. the amount of free space on a disk. > With REST, client and server are exchanging their views of the world. > The client's not instructing the server to change particular fields. > More "Hey, I now consider this object to look like this". > > That can either be compatible, or incompatible (ie, changes to read- > only fields) with the server's policy. Right - default policy should be to ignore changes to read-only fields, but where we think the client is expressing a view that is completely incompatible with our view, then we should return an error - e.g. if the client tries to change the UUID of a VM Cheers, Mark. From bkearney at redhat.com Mon Apr 26 12:14:20 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Mon, 26 Apr 2010 08:14:20 -0400 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1272036050.5275.31.camel@localhost> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> <4BD19F9D.6090109@redhat.com> <1272036050.5275.31.camel@localhost> Message-ID: <4BD5839C.3030401@redhat.com> On 04/23/2010 11:20 AM, David Lutterkort wrote: > On Fri, 2010-04-23 at 09:24 -0400, Bill Burke wrote: >> I think this blurb from one of the blogs describes what I mean perfectly: >> >> "And an IDL is simply a list of API signatures. It doesn't describe >> expected message exchange patterns, required authentication methods, >> message traffic limits, quality of service guarantees, or even pre and >> post conditions for the various method calls. You usually find this >> information in the documentation and/or in the actual business contract >> one signed with the Web service provider. A WADL document for the REST >> Web service will not change this fact." > > Nicely put. I assume that implies that API docs should be in POE (plain > old English) - I am all for that, since I really doubt that any formal > API spec will ever be up-to-date with the code or get real use by > clients. > > In theory (as in: if they weren't so annoying to write, I'd write them), > RelaxNG schemas for XML returned are useful mostly for testing the API > against inadvertant schema changes. > > On a tangent, for Deltacloud core, we have a simple system that > generates what parameters are accepted for each operation from the code. > I wouldn't call that API documentation in any formal sense, more a > gentle reminder to the API user of what's available and how. > > David > > What is the system? -- bk From bkearney at redhat.com Mon Apr 26 12:32:50 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Mon, 26 Apr 2010 08:32:50 -0400 Subject: [rest-practices] Versioning Message-ID: <4BD587F2.5090509@redhat.com> Following up on the earlier thread... if the preferred model to put version information in the media type, or in the url? And.. if in the url, are you starting with a 1 to begin with or if the absence of a number a version 1? -- bk From markmc at redhat.com Mon Apr 26 13:52:22 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Mon, 26 Apr 2010 14:52:22 +0100 Subject: [rest-practices] Versioning In-Reply-To: <4BD587F2.5090509@redhat.com> References: <4BD587F2.5090509@redhat.com> Message-ID: <1272289942.22058.2.camel@blaa> Hey, On Mon, 2010-04-26 at 08:32 -0400, Bryan Kearney wrote: > Following up on the earlier thread... if the preferred model to put > version information in the media type, or in the url? > > And.. if in the url, are you starting with a 1 to begin with or if the > absence of a number a version 1? "Version in url and no version means version 1" makes most sense to me so far: https://www.redhat.com/archives/rest-practices/2010-April/msg00014.html version negotiation is done by the client choosing between e.g. Cheers, Mark. From bmcwhirt at redhat.com Mon Apr 26 14:43:29 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Mon, 26 Apr 2010 10:43:29 -0400 Subject: [rest-practices] Versioning In-Reply-To: <1272289942.22058.2.camel@blaa> References: <4BD587F2.5090509@redhat.com> <1272289942.22058.2.camel@blaa> Message-ID: <4421F931-C70C-40EE-A507-844620CF9AAE@redhat.com> Isn't this where the other week's discussion on content-types, content negotiation, and Accept: headers figure in? The API and the model of the resources is one-in-the-same, really, no? The "API" is just a root synthetic collection or object, sometimes, versionable like any other model entity using content-type. -Bob On Apr 26, 2010, at 9:52 AM, Mark McLoughlin wrote: > Hey, > > On Mon, 2010-04-26 at 08:32 -0400, Bryan Kearney wrote: >> Following up on the earlier thread... if the preferred model to put >> version information in the media type, or in the url? >> >> And.. if in the url, are you starting with a 1 to begin with or if >> the >> absence of a number a version 1? > > "Version in url and no version means version 1" makes most sense to me > so far: > > https://www.redhat.com/archives/rest-practices/2010-April/msg00014.html > > version negotiation is done by the client choosing between e.g. > > > > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From lutter at redhat.com Mon Apr 26 15:24:07 2010 From: lutter at redhat.com (David Lutterkort) Date: Mon, 26 Apr 2010 17:24:07 +0200 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BD5839C.3030401@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> <4BD19F9D.6090109@redhat.com> <1272036050.5275.31.camel@localhost> <4BD5839C.3030401@redhat.com> Message-ID: <1272295447.9273.116.camel@localhost> On Mon, 2010-04-26 at 08:14 -0400, Bryan Kearney wrote: > On 04/23/2010 11:20 AM, David Lutterkort wrote: > > On Fri, 2010-04-23 at 09:24 -0400, Bill Burke wrote: > >> I think this blurb from one of the blogs describes what I mean perfectly: > >> > >> "And an IDL is simply a list of API signatures. It doesn't describe > >> expected message exchange patterns, required authentication methods, > >> message traffic limits, quality of service guarantees, or even pre and > >> post conditions for the various method calls. You usually find this > >> information in the documentation and/or in the actual business contract > >> one signed with the Web service provider. A WADL document for the REST > >> Web service will not change this fact." > > > > Nicely put. I assume that implies that API docs should be in POE (plain > > old English) - I am all for that, since I really doubt that any formal > > API spec will ever be up-to-date with the code or get real use by > > clients. > > > > In theory (as in: if they weren't so annoying to write, I'd write them), > > RelaxNG schemas for XML returned are useful mostly for testing the API > > against inadvertant schema changes. > > > > On a tangent, for Deltacloud core, we have a simple system that > > generates what parameters are accepted for each operation from the code. > > I wouldn't call that API documentation in any formal sense, more a > > gentle reminder to the API user of what's available and how. > > > > David > > > > > What is the system? It's the 'Rabbit DSL' in server/lib/sinatra/rabbit.rb. Best to look at how it's used in server/server.rb. If you have a running driver, go to http://localhost:3001/api/docs for a list of known collections, and for each collection a list of operations on them, together with acceptable parameters (the latter is changed on server start, depending on the features the driver provides) I'd like to eventually integrate that with the results of the API proper, but I think it needs to solidify a little more before we can do that. David From iheim at redhat.com Tue Apr 27 13:40:22 2010 From: iheim at redhat.com (Itamar Heim) Date: Tue, 27 Apr 2010 09:40:22 -0400 (EDT) Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <1272036050.5275.31.camel@localhost> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> <4BD19F9D.6090109@redhat.com> <1272036050.5275.31.camel@localhost> Message-ID: <4b7101cae60e$f367fed0$da37fc70$@com> > From: rest-practices-bounces at redhat.com [mailto:rest-practices- > bounces at redhat.com] On Behalf Of David Lutterkort > Sent: Friday, April 23, 2010 18:21 PM > To: Bill Burke > Cc: rest-practices at redhat.com > Subject: Re: [rest-practices] Read-only fields in a representation type > > On Fri, 2010-04-23 at 09:24 -0400, Bill Burke wrote: > > I think this blurb from one of the blogs describes what I mean > perfectly: > > > > "And an IDL is simply a list of API signatures. It doesn't describe > > expected message exchange patterns, required authentication methods, > > message traffic limits, quality of service guarantees, or even pre > and > > post conditions for the various method calls. You usually find this > > information in the documentation and/or in the actual business > contract > > one signed with the Web service provider. A WADL document for the > REST > > Web service will not change this fact." > > Nicely put. I assume that implies that API docs should be in POE (plain > old English) - I am all for that, since I really doubt that any formal > API spec will ever be up-to-date with the code or get real use by > clients. [IH] why would we send a developer to read documentation and start trying to access code, compared to WSDL, which the developer can point and click, and get generated code that gives him something useful like intelisense? What is so wrong with having metadata format for REST that will ease the developer life? From eglynn at redhat.com Tue Apr 27 16:58:39 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Tue, 27 Apr 2010 17:58:39 +0100 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <1271786704.3965.176.camel@quark> References: <1271704843.3965.20.camel@quark> <4BCDA153.5090401@redhat.com> <1271786704.3965.176.camel@quark> Message-ID: <1272387520.17074.214.camel@quark> Folks, I've been experimenting with various ways for a client to indicate that it wishes an action to be executed asynchronously, as opposed to blocking for completion. The idea would be to make this asynchrony optional so as to facilitate really simple clients which may not be set up to easily poll for completion. Now I don't really like the idea of using an "?async=true" style of query parameter, as this would tend to bleed knowledge of the URI structure onto the client side. In the case where the POST entity-body is non-empty (e.g. for migrate we might indicate a target host, or for reboot maybe a grace period or somesuch), then the async preference could simply be encoded in the task representation. But some actions are likely to have a empty body, and I'm leery about adding one just for the sake of the client's async preference. Another option would be to leverage the standard Expect header, with a custom expectation-extension in the style of the familiar "Expect: 100-Continue" usage. So the client of a long-running action could set a header something with like "Expect: 202-Accepted", which the service would take as an explicit instruction to spin off an async task and return a 202. If the action could not be carried out in a non-blocking fashion for some reason, the service would bail with a 417 Expectation Failed. Is there a whiff of sulphur around extending the semantics of an existing header in this way? Is it likely to cause trouble with intermediating proxies? There are some worrying comments in the RFC[1] to the effect that proxies must understand the expectation. Cheers, Eoghan [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.20 On Tue, 2010-04-20 at 19:05 +0100, Eoghan Glynn wrote: > Thanks for the feedback, folks. > > So I've been chewing away on our requirements around minimal updates to > search queries and also the asynchronous actions discussed on this > thread. > > I'm tending towards a design whereby we maintain a sort of three-level > cache of VM-related representations: > > 1. The VM collection, which represents our best state of knowledge of > the current status of each VM. This is used to populate the response to > GET /vms?query=... style operations. > > 2. A list of completed VM state changes, only the most recent for each > VM. The length of this list is bounded by the VM collection size, but > its also aggressively reaped, so in general it would be much smaller. > The idea is to return a link to the next free slot in this list along > with the result of any queries evaluated over the entire VM collection > in #1, so that a client can periodically refresh its query result set > without re-evaluating the entire query. The client effectively polls on > the tail of the update list, only seeing those state changes that > occured _after_ its initial GET. A retrieval on a reaped VM state-change > resource is simply 301-redirected back to the main collection. > > 3. A potentially larger queue of pending or in-progress actions, of > which there may be more than one outstanding per VM (in the case of a > sequence of actions being submitted in quick succession). A reference to > a resource representing the corresponding action is returned with the > initial 202 Accepted response to the POST on an action URI. Once the > task is completed, whether it succeeded or failed, this resource becomes > part of the audit trail and is effectively persisted, presumably with a > longer lifespan than any reasonable client. > > So #2 allows client to efficiently refresh their queries without any > dependence on special handling of If-Modified-Since, whereas #3 skates > around the statefulness prohibition. > > Cheers, > Eoghan > > > On Tue, 2010-04-20 at 08:42 -0400, Bryan Kearney wrote: > > On 04/19/2010 03:20 PM, Eoghan Glynn wrote: > > > > > > Hi Folks, > > > > > > I wanted to get your feeling on the question of breaking statelessness > > > when asynchronous operations are used, in particular in terms of the > > > protocol used to check the outcome of the deferred task. > > > > > > So say we need to model a potentially long-lived operation, such as > > > migrating a VM. To avoid tying up a connection for the duration, the > > > server could respond to the "POST /vms/999/reboot" request with a 202 > > > Accepted, along with a unique URI to be used subsequently to check on > > > the status of the migration. > > > > > > > Perhaps, you model it like a collection of actions. So.. you POST to > > > > /vms/999/rebootRequests > > > > which gives you back a resource which looks like (pardon the xml) > > > > > > SOME DATE > > SOME DUDE > > SOME STATUS > > > > > > This way, the request itself is a resource. Assuming infinate DB Space, > > you keep it for the life of the machine. > > > > Or.. a post to reboot could redirect you to /vms/999/actions > > > > Which gives you the same basic object > > > > > > reboot > > SOME DATE > > SOME DUDE > > SOME STATUS > > > > > > > > > Now it's the lifecycle of the temporary resource represented by this URI > > > that seems to be potentially problematic. While the async operation is > > > still in flight, there's no problem. However the question is how long > > > _after_ the operation has completed should we maintain this resource so > > > that the client can eventually determine the outcome? We've no guarantee > > > that the client will poll regularly, so say we impose some arbitrary > > > expiry, maybe 10 minutes after the task has completed. But even for that > > > limited time we seem to be breaking one of the fundamental Fielding > > > commandments, the one that demands session state is kept entirely on the > > > client side. After the task completes, this URI no longer represents a > > > resource per se, rather we'd just be keeping it around for a while to > > > support our conversation with the client. > > > > > > So another more extreme approach would be to limit the client to: > > > > > > (a) checking whether the async operation is still being processed, so > > > that the status URI is only valid until the task completes, > > > > > > (b) inferring from the current state of the VM whether the task may have > > > succeeded or failed, for example the client gets a big hint that its > > > stop operation has failed if the task has completed but the VM state > > > hasn't transitioned to DOWN (or course there's a race here, as the VM > > > may simply have been restarted in the meantime by another agent), > > > > > > and, > > > > > > (c) getting a indirect indication of the failure reason by scanning an > > > event/audit log. > > > > > > I am also fine with querying the state of the object.. but I bet you > > have a need for a log anyways. > > > > -- bk > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From markmc at redhat.com Tue Apr 27 20:06:17 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 27 Apr 2010 21:06:17 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BD1AF8C.1060106@redhat.com> References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> Message-ID: <1272398777.7594.138.camel@blaa> On Fri, 2010-04-23 at 10:32 -0400, Perry Myers wrote: > For cloud related efforts, we want to make sure that all of our usages of > REST are consistent wrt style/best practices. Ideally, it would be best > if all Red Hat REST usage is on the same page. But barring that, the > cloud usage should at least be consistent. > > So bburke's REST pages are certainly a good starting poing wrt > style/usage. But Mark M. will also be maintaining a separate wiki page > (he'll provide the link) that is specific to cloud usage of REST. > Hopefully it won't duplicate all of the good work that bburke has done, > but instead will just point out style differences between his pages and > what cloud folks agree on. > > It will be expected that all cloud developers will conform to the style as > agreed upon in Mark's wiki page. Okay, I've taken a very rough first cut at this: http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide Please feel free to edit or discuss here. Everything is still open for discussion. Please do try and keep topics in separate threads so that we can easily reference the discussion from the wiki. Yes, I've posted to fedoraproject.org/wiki. I didn't want to use bburke's jboss.org page since it may end up being a cloud org specific style guide. I considered using et.redhat.com/wiki but I figure even less people on this list has an account there than fedora. AFAIR, all you need to do to edit the fedora wiki is create an account and agree to the CLA (or join the cla_redhat group). See here: https://fedoraproject.org/wiki/Account_System/NewAccount Thanks, Mark. From markmc at redhat.com Tue Apr 27 20:19:13 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 27 Apr 2010 21:19:13 +0100 Subject: [rest-practices] Versioning In-Reply-To: <4421F931-C70C-40EE-A507-844620CF9AAE@redhat.com> References: <4BD587F2.5090509@redhat.com> <1272289942.22058.2.camel@blaa> <4421F931-C70C-40EE-A507-844620CF9AAE@redhat.com> Message-ID: <1272399553.7594.151.camel@blaa> On Mon, 2010-04-26 at 10:43 -0400, Bob McWhirter wrote: > Isn't this where the other week's discussion on content-types, content > negotiation, and Accept: headers figure in? The API and the model of > the resources is one-in-the-same, really, no? The "API" is just a > root synthetic collection or object, sometimes, versionable like any > other model entity using content-type. Yes, yes and yes :) To be clear - I'm only talking here about incompatible versioning of incompatible revisions of the interface. I don't think we need versions for compatible revisions. And we also should very, very rarely have incompatible revisions. My understanding of the previous discussion was that we were leaning towards not using media type versions for incompatible revisions e.g. https://www.redhat.com/archives/rest-practices/2010-April/msg00008.html What I've read is that a different URL scheme might be preferable for clients that are not able to participate in HTTP content negotiation (like a browser). If you're following the guideline of not exposing your URL schemes and instead using links, then things actually become simpler for the client as it doesn't have to set any Accept headers. https://www.redhat.com/archives/rest-practices/2010-April/msg00017.html But I tent to think that content negociation makes things way harder (and fragile) than they should. A versioned URI space if you really want to decouple different version support is the simplest IMHO. Given that we're talking about (hopefully) very rare incompatible changes, I much prefer the simplicity of doing the versioning in the URIs. This is one of the reasons I wanted the style guide thing - so we can be clear whether we're actually coming to agreement on things or not :-) Cheers, Mark. From markmc at redhat.com Tue Apr 27 20:23:47 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Tue, 27 Apr 2010 21:23:47 +0100 Subject: [rest-practices] text/html representation? Message-ID: <1272399827.7594.156.camel@blaa> Hey, I was trying to think of some simple advice for people designing REST APIs - things like "if you're documenting the URI scheme, it's not HATEOAS" Would it be a worthwhile exercise for API designers to add a text/html representation of their resources? with forms for action buttons etc. That way you could be confident your really API is hypertext driven. It would also be a nice way for API users to browse the API Just a thought ... Cheers, Mark. From bmcwhirt at redhat.com Tue Apr 27 22:15:47 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Tue, 27 Apr 2010 18:15:47 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <1272399827.7594.156.camel@blaa> References: <1272399827.7594.156.camel@blaa> Message-ID: <05AF1E64-0B69-44A6-B981-6F7D00243741@redhat.com> I've certainly created HTML and
-centric representations and helpers before. I think the next one I create will be a purely HTML UI, but rely on fondling JSON to actually do anything of note. No reason to do extra work to support POST'd s and such, when we have a perfectly usable JSON-centric API just waiting to be consumed. Plus, you get "using X service from javascript with json" examples "for free". -Bob On Apr 27, 2010, at 4:23 PM, Mark McLoughlin wrote: > Hey, > > I was trying to think of some simple advice for people designing REST > APIs - things like "if you're documenting the URI scheme, it's not > HATEOAS" > > Would it be a worthwhile exercise for API designers to add a text/html > representation of their resources? with forms for action buttons etc. > > That way you could be confident your really API is hypertext driven. > It > would also be a nice way for API users to browse the API > > Just a thought ... > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From bkearney at redhat.com Wed Apr 28 01:24:37 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Tue, 27 Apr 2010 21:24:37 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <1272399827.7594.156.camel@blaa> References: <1272399827.7594.156.camel@blaa> Message-ID: <4BD78E55.20803@redhat.com> On 04/27/2010 04:23 PM, Mark McLoughlin wrote: > Hey, > > I was trying to think of some simple advice for people designing REST > APIs - things like "if you're documenting the URI scheme, it's not > HATEOAS" This implies a level of maturity on the client which the tooling does not help yet. I would put Hateoas as a goal to strive for, not a hard requirement now. > > Would it be a worthwhile exercise for API designers to add a text/html > representation of their resources? with forms for action buttons etc. I would be wary of adding serializers here. Plus... adding authentication may require the notion of state (e.g. credentials, certs, etc) on the client which the API will not require. > > That way you could be confident your really API is hypertext driven. It > would also be a nice way for API users to browse the API > > Just a thought ... Maybe an XST layer :) Who worked with Cocoon back in the day? -- bk From mlittle at redhat.com Mon Apr 26 09:58:37 2010 From: mlittle at redhat.com (Mark Little) Date: Mon, 26 Apr 2010 10:58:37 +0100 Subject: [rest-practices] Read-only fields in a representation type In-Reply-To: <4BD1987B.6090003@redhat.com> References: <1271773334.3965.84.camel@quark> <1271791925.1633.34.camel@blaa> <4BCE0350.4010701@redhat.com> <4BCEFBB9.7010509@redhat.com> <4BCF144D.9020807@redhat.com> <4BCF1643.6070604@redhat.com> <4BCF1720.4020400@redhat.com> <4BCF1E25.6060004@redhat.com> <4BD1987B.6090003@redhat.com> Message-ID: On 23 Apr 2010, at 13:54, Bryan Kearney wrote: > On 04/23/2010 08:30 AM, Mark Little wrote: >> The debate as to whether or not to use WADL isn't tied to HATEOS, >> which >> as you know is only one aspect of REST: the reasons not to use it go >> much deeper than that. I assume you've checked out various resources >> like ... > > Well.. that is the common refrain. If you are describing the URLs, > you _must_ not be using the links, and therefore you are too tightly > coupled to the server. Depends who you listen to. Most of the time I hear WADL mentioned it's in the context of how it's not needed at all in RESTful systems. Here are a few more links you may want to check. The first covers some important topics that we address in SOA in general (REST can be used as the basis for SOA). Specifically some of the work we've been doing around Process Governance and contract-first designs, are relevant too. http://service-architecture.blogspot.com/2010/02/why-contracts-are-more-important-than.html Then everyone should read this. And then read it again. http://www.w3.org/TR/webarch/ This is an excellent presentation on a real-world RESTful system. http://www.infoq.com/presentations/restful-financial-systems- integration (http://www.slideshare.net/KirkWylie/restful-approaches-to-financial-systems-integration ) - not a reference to WADL in sight. And this shows have WSDL 2.0 could be used as a substitute for WADL. No, I'm not recommending it, but it's for completeness. http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/ > > I find it interesting that the on ramp to rest is "it is simpler", > which it is when you go the bookmark approach, and send http > requests to known resource locations. If I was asked to write a > client against "ThatKoolRestAPI" then either: > > 1) The developers had better documented every resource, and every > action link which is possible from each link > > or > > 2) I have to execute each path manually (or with loggin) to see what > I can do next. > > Since I tend not to trust developers to always update the > documentation, it seems like an automated means to do (1) would be > valuable to the API writers as well as documenters. Note, I am not > advocation IDL driven development. Develop the code, generate the IDL. This is very similar to what we/I did for quite a few of the later WS- * standards, such as WS-TX and WS-RM: develop the on-the-wire messages first and then retrofit the WSDL afterwards. Most implementations I know still ignore the WSDL these days, with the message format being the normative definition. Kind of makes you wonder if the WSDL is worth it at all ;-) > > >> >> http://www.25hoursaday.com/weblog/2007/06/04/WhatsWrongWithWADL.aspx >> http://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl >> >> http://www.markbaker.ca/blog/2007/05/rest-wadl-forest-trees/comment-page-1/ >> http://www.innoq.com/blog/st/2007/06/wadl_just_a_hypermedia_format.html >> http://www.tbray.org/ongoing/When/200x/2007/05/28/REST >> http://www.mnot.net/blog/2008/01/21/wadl_watching >> http://www.infoq.com/news/2007/03/WADL > > Some of the these are against it, but much of the haters are in the > comments. The best valuable comments are from the fist link which > talk about the issues of using XSD as the means to validate. I think > these are valid. I would rather see the discussion be around how to > make a good descriptor syntax, but it seems to be focused on "why > would you ever want to describe your API?" I think the pragmatic approach that Bill is taking around REST-* is right. Maybe there should be a public discussion forum on this within the REST-* effort. Bill? Mark. --- Mark Little mlittle at redhat.com JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland). From eglynn at redhat.com Wed Apr 28 08:35:41 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Wed, 28 Apr 2010 09:35:41 +0100 Subject: [rest-practices] text/html representation? In-Reply-To: <1272399827.7594.156.camel@blaa> References: <1272399827.7594.156.camel@blaa> Message-ID: <1272443741.17074.283.camel@quark> One slight issue for a browser-driven interaction would be where the API goes even slightly off-piste with HTTP headers, status codes and the likes. A bare browser is probably not going to give visibility to all these aspects of the interaction. Though of course something slightly smarter like an AJAX client could. Cheers, Eoghan On Tue, 2010-04-27 at 21:23 +0100, Mark McLoughlin wrote: > Hey, > > I was trying to think of some simple advice for people designing REST > APIs - things like "if you're documenting the URI scheme, it's not > HATEOAS" > > Would it be a worthwhile exercise for API designers to add a text/html > representation of their resources? with forms for action buttons etc. > > That way you could be confident your really API is hypertext driven. It > would also be a nice way for API users to browse the API > > Just a thought ... > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From bburke at redhat.com Wed Apr 28 12:14:30 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 28 Apr 2010 08:14:30 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <1272399827.7594.156.camel@blaa> References: <1272399827.7594.156.camel@blaa> Message-ID: <4BD826A6.8090801@redhat.com> A weird idea has been going through my head lately. What if, for when its practical, have your edit/action links accept application/x-www-form-urlencoded, and the rel attribute of the link points to an html form describing the interaction. Mark McLoughlin wrote: > Hey, > > I was trying to think of some simple advice for people designing REST > APIs - things like "if you're documenting the URI scheme, it's not > HATEOAS" > > Would it be a worthwhile exercise for API designers to add a text/html > representation of their resources? with forms for action buttons etc. > > That way you could be confident your really API is hypertext driven. It > would also be a nice way for API users to browse the API > > Just a thought ... > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From markmc at redhat.com Wed Apr 28 12:37:22 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Wed, 28 Apr 2010 13:37:22 +0100 Subject: [rest-practices] text/html representation? In-Reply-To: <4BD826A6.8090801@redhat.com> References: <1272399827.7594.156.camel@blaa> <4BD826A6.8090801@redhat.com> Message-ID: <1272458242.2739.100.camel@blaa> Yeah, I was thinking along similar lines With html, a form describes the parameters which can be POSTed Does a RESTful API need something similar for parameters to an action link? We had been assuming any action parameters would be passed using an xml/json/etc. representation of the "action resource", but if we take the html form analogy, we could actually pass them using query parameters using application/x-www-form-urlencoded as you say I'm thinking along the lines of: ... > HATEOAS" > > > > Would it be a worthwhile exercise for API designers to add a text/html > > representation of their resources? with forms for action buttons etc. > > > > That way you could be confident your really API is hypertext driven. It > > would also be a nice way for API users to browse the API > > > > Just a thought ... > > > > Cheers, > > Mark. > > > > _______________________________________________ > > rest-practices mailing list > > rest-practices at redhat.com > > https://www.redhat.com/mailman/listinfo/rest-practices > From bkearney at redhat.com Wed Apr 28 12:43:07 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Wed, 28 Apr 2010 08:43:07 -0400 Subject: [rest-practices] rest-practices purpose In-Reply-To: <1272398777.7594.138.camel@blaa> References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> <1272398777.7594.138.camel@blaa> Message-ID: <4BD82D5B.1090309@redhat.com> On 04/27/2010 04:06 PM, Mark McLoughlin wrote: > On Fri, 2010-04-23 at 10:32 -0400, Perry Myers wrote: > >> For cloud related efforts, we want to make sure that all of our usages of >> REST are consistent wrt style/best practices. Ideally, it would be best >> if all Red Hat REST usage is on the same page. But barring that, the >> cloud usage should at least be consistent. >> >> So bburke's REST pages are certainly a good starting poing wrt >> style/usage. But Mark M. will also be maintaining a separate wiki page >> (he'll provide the link) that is specific to cloud usage of REST. >> Hopefully it won't duplicate all of the good work that bburke has done, >> but instead will just point out style differences between his pages and >> what cloud folks agree on. >> >> It will be expected that all cloud developers will conform to the style as >> agreed upon in Mark's wiki page. > > Okay, I've taken a very rough first cut at this: > > http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide > > Please feel free to edit or discuss here. Everything is still open for > discussion. Please do try and keep topics in separate threads so that we > can easily reference the discussion from the wiki. Great first cut! Comments below Intro I will stop harping on this. But I like the idea of "levels" of the API based on the number of principals which you achieve. Guidelines - In XML: Can we assume all elements? This effects how we marshal to JSON. - In urls, should query paramaters be puthon styled? Also. .I assume we use query parameters not form parameters. - Another item to discuss would be return codes, and how to handle error messages. For example, we are using a specific http return code for error types. We do not have sub messages, but we put a localized message into a json blob in the body of the message which is returned. It would be nice to standardize on that message, and the use of return codes. - Also, on return codes, it would be nice to standardize on the return codes. So.. should Creates (POST to FOO) return the new object and not a 204? Should deletes return a 204? - Another discussion we have had is on how to handle object graphs. Lets assume we have a resource model which is "Company -> Department -> Employee". We have assumed the API would start at a resource and "go down". So, in this case the following apis could be supported: companies/{company_uuid}/departments/{dept_uuid}/employees/{emp_id} departments/{dept_uuid}/employees/{emp_id} However, we would not support departments/{dept_uuid}/company - I assume urls and xml collections are plural resource names - Finally, the last thing we discussed was how does security fit in with collections. We have assumed that if user 1 calls companies/{company_uuid}/departments they may see a different collection from user 2 based on their roles and permissions. -- bk From bburke at redhat.com Wed Apr 28 13:18:50 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 28 Apr 2010 09:18:50 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <1272458242.2739.100.camel@blaa> References: <1272399827.7594.156.camel@blaa> <4BD826A6.8090801@redhat.com> <1272458242.2739.100.camel@blaa> Message-ID: <4BD835BA.30104@redhat.com> Mark McLoughlin wrote: > Yeah, I was thinking along similar lines > > With html, a form describes the parameters which can be POSTed > > Does a RESTful API need something similar for parameters to an action > link? > IMO, its overkill. Unless elements are going to be rendered, I don't see the point of embedding descriptive information other than a schema URL or link rel URL. Let the rel attribute point to an html form: ... Or, if not the rel attribute, define a new attribute. > We had been assuming any action parameters would be passed using an > xml/json/etc. representation of the "action resource", but if we take > the html form analogy, we could actually pass them using query > parameters using application/x-www-form-urlencoded as you say > > I'm thinking along the lines of: > > > ... > > > > References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> <1272398777.7594.138.camel@blaa> <4BD82D5B.1090309@redhat.com> Message-ID: <4BD8382C.8080702@redhat.com> Bryan Kearney wrote: > On 04/27/2010 04:06 PM, Mark McLoughlin wrote: >> On Fri, 2010-04-23 at 10:32 -0400, Perry Myers wrote: >> >>> For cloud related efforts, we want to make sure that all of our >>> usages of >>> REST are consistent wrt style/best practices. Ideally, it would be best >>> if all Red Hat REST usage is on the same page. But barring that, the >>> cloud usage should at least be consistent. >>> >>> So bburke's REST pages are certainly a good starting poing wrt >>> style/usage. But Mark M. will also be maintaining a separate wiki page >>> (he'll provide the link) that is specific to cloud usage of REST. >>> Hopefully it won't duplicate all of the good work that bburke has done, >>> but instead will just point out style differences between his pages and >>> what cloud folks agree on. >>> >>> It will be expected that all cloud developers will conform to the >>> style as >>> agreed upon in Mark's wiki page. >> >> Okay, I've taken a very rough first cut at this: >> >> http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide >> >> Please feel free to edit or discuss here. Everything is still open for >> discussion. Please do try and keep topics in separate threads so that we >> can easily reference the discussion from the wiki. > > Great first cut! Comments below > > > Intro > I will stop harping on this. But I like the idea of "levels" of the API > based on the number of principals which you achieve. > > Guidelines > - In XML: Can we assume all elements? This effects how we marshal to JSON. > > - In urls, should query paramaters be puthon styled? Also. .I assume we > use query parameters not form parameters. > > - Another item to discuss would be return codes, and how to handle error > messages. For example, we are using a specific http return code for > error types. We do not have sub messages, but we put a localized message > into a json blob in the body of the message which is returned. It would > be nice to standardize on that message, and the use of return codes. > > - Also, on return codes, it would be nice to standardize on the return > codes. So.. should Creates (POST to FOO) return the new object and not a > 204? Should deletes return a 204? > > - Another discussion we have had is on how to handle object graphs. Lets > assume we have a resource model which is "Company -> Department -> > Employee". We have assumed the API would start at a resource and "go > down". So, in this case the following apis could be supported: > > companies/{company_uuid}/departments/{dept_uuid}/employees/{emp_id} > departments/{dept_uuid}/employees/{emp_id} > > However, we would not support > > departments/{dept_uuid}/company > > - I assume urls and xml collections are plural resource names > > - Finally, the last thing we discussed was how does security fit in with > collections. We have assumed that if user 1 calls > > companies/{company_uuid}/departments > > they may see a different collection from user 2 based on their roles and > permissions. > You really need to rename the "actions" section to "Modeling Operations". Modeling operations, as we've already discussed, is about the most difficult thing to understand and get right with REST. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Wed Apr 28 13:32:19 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 28 Apr 2010 09:32:19 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <4BD78E55.20803@redhat.com> References: <1272399827.7594.156.camel@blaa> <4BD78E55.20803@redhat.com> Message-ID: <4BD838E3.9020607@redhat.com> Bryan Kearney wrote: > On 04/27/2010 04:23 PM, Mark McLoughlin wrote: >> Hey, >> >> I was trying to think of some simple advice for people designing REST >> APIs - things like "if you're documenting the URI scheme, it's not >> HATEOAS" > > This implies a level of maturity on the client which the tooling does > not help yet. I would put Hateoas as a goal to strive for, not a hard > requirement now. > Not sure I agree with "not a hard requirement". How would you feel if a naming service was not a hard requirement and you had to hard code IORs everywhere? IMO, you at least need link templates, i.e. If you ever want to change your URI schemes you're gonna have a hard time updating and supporting older clients. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bkearney at redhat.com Wed Apr 28 12:56:10 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Wed, 28 Apr 2010 08:56:10 -0400 Subject: [rest-practices] text/html representation? In-Reply-To: <1272458242.2739.100.camel@blaa> References: <1272399827.7594.156.camel@blaa> <4BD826A6.8090801@redhat.com> <1272458242.2739.100.camel@blaa> Message-ID: <4BD8306A.10805@redhat.com> On 04/28/2010 08:37 AM, Mark McLoughlin wrote: > Yeah, I was thinking along similar lines > > With html, a form describes the parameters which can be POSTed > > Does a RESTful API need something similar for parameters to an action > link? > > We had been assuming any action parameters would be passed using an > xml/json/etc. representation of the "action resource", but if we take > the html form analogy, we could actually pass them using query > parameters using application/x-www-form-urlencoded as you say > > I'm thinking along the lines of: > > > ... > > > > based on the number of principals which you achieve. Good idea. I suggest two levels - "sucky" and "not sucky" (Sorry, couldn't resist :-) I do like the idea, in general - it's a way of saying "I'm 95% RESTful, get off my back about the other 5%" Specifically with our APIs, though, I'm think we should strive for HATEOAS > Guidelines > - In XML: Can we assume all elements? This effects how we marshal to JSON. The perennial XML debate ... And example I'm looking at right now: ... ... makes more sense to me than: nfs ... ... same for e.g.: Department -> > Employee". We have assumed the API would start at a resource and "go > down". So, in this case the following apis could be supported: > > companies/{company_uuid}/departments/{dept_uuid}/employees/{emp_id} > departments/{dept_uuid}/employees/{emp_id} > > However, we would not support > > departments/{dept_uuid}/company Nice topic - could you kick off a separate thread on this? I was just hitting a similar question > - I assume urls and xml collections are plural resource names Yep, added > - Finally, the last thing we discussed was how does security fit in with > collections. We have assumed that if user 1 calls > > companies/{company_uuid}/departments > > they may see a different collection from user 2 based on their roles and > permissions. Yep, that goes for e.g. actions too - I've added the start of a security section with this Cheers, Mark. From markmc at redhat.com Wed Apr 28 16:30:31 2010 From: markmc at redhat.com (Mark McLoughlin) Date: Wed, 28 Apr 2010 17:30:31 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <4BD8382C.8080702@redhat.com> References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> <1272398777.7594.138.camel@blaa> <4BD82D5B.1090309@redhat.com> <4BD8382C.8080702@redhat.com> Message-ID: <1272472231.2739.140.camel@blaa> On Wed, 2010-04-28 at 09:29 -0400, Bill Burke wrote: > You really need to rename the "actions" section to "Modeling > Operations". Modeling operations, as we've already discussed, is about > the most difficult thing to understand and get right with REST. Done: http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#Modelling_Operations I had your blog on this listed at the very end, I've moved it up into the section itself now, though. Cheers, Mark. From eglynn at redhat.com Wed Apr 28 16:48:32 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Wed, 28 Apr 2010 17:48:32 +0100 Subject: [rest-practices] rest-practices purpose In-Reply-To: <1272472068.2739.139.camel@blaa> References: <4BC609F8.6020502@redhat.com> <4BD1AF8C.1060106@redhat.com> <1272398777.7594.138.camel@blaa> <4BD82D5B.1090309@redhat.com> <1272472068.2739.139.camel@blaa> Message-ID: <1272473312.25667.20.camel@quark> On Wed, 2010-04-28 at 17:27 +0100, Mark McLoughlin wrote: > On Wed, 2010-04-28 at 08:43 -0400, Bryan Kearney wrote: > > Intro > > I will stop harping on this. But I like the idea of "levels" of the API > > based on the number of principals which you achieve. > > Good idea. I suggest two levels - "sucky" and "not sucky" > > (Sorry, couldn't resist :-) > > I do like the idea, in general - it's a way of saying "I'm 95% RESTful, > get off my back about the other 5%" > > Specifically with our APIs, though, I'm think we should strive for > HATEOAS Leonard Richardson has a multi-level maturity model for REST, explained here[1] by Fowler and described here[2] by the man himself. Unfortunately though, from our point of view most of the action lies between levels 2 and 3, so to be really useful we'd need to interpose a few 2.x levels. /Eoghan [1] http://martinfowler.com/articles/richardsonMaturityModel.html [2] http://www.crummy.com/writing/speaking/2008-QCon/act3.html From eoghan.glynn at gmail.com Thu Apr 29 10:55:07 2010 From: eoghan.glynn at gmail.com (Eoghan Glynn) Date: Thu, 29 Apr 2010 11:55:07 +0100 Subject: [rest-practices] Namespace qualifying respresentation types Message-ID: Folks, I wanted to get the group's feeling for the use of namespaces in representation types. The context for the question initially comes from a discussion about how action/operations were to be modelled in RHEVM-API, particularly how to capture the action-specific parameter types in the schema. In XML schema terms, my first cut was to use an xs:any within the action element, but to restrict the contained type to the local namespace. Which of course requires that a target namespace is defined in the first place. So I'm sensing there may be some opposition to this, given that namespacing isn't widely used in the existing RESTful APIs. I guess I'm wondering whether this ommission was a concious decision, or just that nobody saw the need for using namespaces but wouldn't be averse to their use in principle. Obviously there are other RESTful examples out there in the wild where the xmlns attribute makes an appearance, Atom springs to mind here ... . And I don't need to rehearse the basic advantages of using namespaces, partitioning the global namespace, aiding in validation, encoding version information etc. But I would be interested in hearing if there's determined opposition to their use, and if so what the reasoning is. Thanks, Eoghan -------------- next part -------------- An HTML attachment was scrubbed... URL: From mlittle at redhat.com Thu Apr 29 13:45:55 2010 From: mlittle at redhat.com (Mark Little) Date: Thu, 29 Apr 2010 14:45:55 +0100 Subject: [rest-practices] Versioning In-Reply-To: <1272399553.7594.151.camel@blaa> References: <4BD587F2.5090509@redhat.com> <1272289942.22058.2.camel@blaa> <4421F931-C70C-40EE-A507-844620CF9AAE@redhat.com> <1272399553.7594.151.camel@blaa> Message-ID: http://www.informit.com/articles/article.aspx?p=1566460 On 27 Apr 2010, at 21:19, Mark McLoughlin wrote: > On Mon, 2010-04-26 at 10:43 -0400, Bob McWhirter wrote: >> Isn't this where the other week's discussion on content-types, >> content >> negotiation, and Accept: headers figure in? The API and the model of >> the resources is one-in-the-same, really, no? The "API" is just a >> root synthetic collection or object, sometimes, versionable like any >> other model entity using content-type. > > Yes, yes and yes :) > > To be clear - I'm only talking here about incompatible versioning of > incompatible revisions of the interface. I don't think we need > versions > for compatible revisions. And we also should very, very rarely have > incompatible revisions. > > My understanding of the previous discussion was that we were leaning > towards not using media type versions for incompatible revisions e.g. > > https://www.redhat.com/archives/rest-practices/2010-April/msg00008.html > > What I've read is that a different URL scheme might be preferable for > clients that are not able to participate in HTTP content negotiation > (like a browser). If you're following the guideline of not exposing > your URL schemes and instead using links, then things actually become > simpler for the client as it doesn't have to set any Accept headers. > > https://www.redhat.com/archives/rest-practices/2010-April/msg00017.html > > But I tent to think that content negociation makes things way harder > (and fragile) than they should. A versioned URI space if you really > want > to decouple different version support is the simplest IMHO. > > > Given that we're talking about (hopefully) very rare incompatible > changes, I much prefer the simplicity of doing the versioning in the > URIs. > > This is one of the reasons I wanted the style guide thing - so we > can be > clear whether we're actually coming to agreement on things or not :-) > > Cheers, > Mark. > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices --- Mark Little mlittle at redhat.com JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland). From eglynn at redhat.com Thu Apr 29 19:16:24 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Thu, 29 Apr 2010 20:16:24 +0100 Subject: [rest-practices] Async operations and statelessness In-Reply-To: <1272387520.17074.214.camel@quark> References: <1271704843.3965.20.camel@quark> <4BCDA153.5090401@redhat.com> <1271786704.3965.176.camel@quark> <1272387520.17074.214.camel@quark> Message-ID: <1272568585.3698.1.camel@quark> Unfortunately this expectation-setting approach is not going to fly, for the reason explained here: https://fedorahosted.org/pipermail/rhevm-api/2010-April/000146.html /Eoghan On Tue, 2010-04-27 at 17:58 +0100, Eoghan Glynn wrote: > Folks, > > I've been experimenting with various ways for a client to indicate that > it wishes an action to be executed asynchronously, as opposed to > blocking for completion. The idea would be to make this asynchrony > optional so as to facilitate really simple clients which may not be set > up to easily poll for completion. > > Now I don't really like the idea of using an "?async=true" style of > query parameter, as this would tend to bleed knowledge of the URI > structure onto the client side. > > In the case where the POST entity-body is non-empty (e.g. for migrate we > might indicate a target host, or for reboot maybe a grace period or > somesuch), then the async preference could simply be encoded in the task > representation. But some actions are likely to have a empty body, and > I'm leery about adding one just for the sake of the client's async > preference. > > Another option would be to leverage the standard Expect header, with a > custom expectation-extension in the style of the familiar "Expect: > 100-Continue" usage. > > So the client of a long-running action could set a header something with > like "Expect: 202-Accepted", which the service would take as an explicit > instruction to spin off an async task and return a 202. If the action > could not be carried out in a non-blocking fashion for some reason, the > service would bail with a 417 Expectation Failed. > > Is there a whiff of sulphur around extending the semantics of an > existing header in this way? Is it likely to cause trouble with > intermediating proxies? There are some worrying comments in the RFC[1] > to the effect that proxies must understand the expectation. > > Cheers, > Eoghan > > > [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.20 From veillard at redhat.com Fri Apr 30 14:19:24 2010 From: veillard at redhat.com (Daniel Veillard) Date: Fri, 30 Apr 2010 16:19:24 +0200 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: References: Message-ID: <20100430141924.GK32184@redhat.com> On Thu, Apr 29, 2010 at 11:55:07AM +0100, Eoghan Glynn wrote: > Folks, > > I wanted to get the group's feeling for the use of namespaces in > representation types. > > The context for the question initially comes from a discussion about how > action/operations were to be modelled in RHEVM-API, particularly how to > capture the action-specific parameter types in the schema. In XML schema > terms, my first cut was to use an xs:any within the action element, but to > restrict the contained type to the local namespace. Which of course requires > that a target namespace is defined in the first place. Why XML Schemas ? Why not Relax-NG instead. As an implementor, I *strongly* suggest to avoid XSD unless for very very simple things. And even very simple thing are described in very painful terms with no formal semantic. No later than today I had to dig in http://www.w3.org/TR/xmlschema-1/#Simple_Type_Definition_details for some other Red Hat employees requesting help. This thing is horrid please avoid it. In contrast Relax-NG specification is 1/ clear 2/ includes a formal semantic description 3/ has more expressive power than XSD and is even an ISO standard. http://www.oasis-open.org/committees/relax-ng/spec-20011203.html Actually I would be very surprised if there wasn't a way to use xs:any allowing only non-namespaced elements, but considering the lack of clarity of the spec, no matter everybody gets confused. In the end people just try with the set of implementation tehy target and don't try to understand the real expected semantic of their schemas, which IMHO completely undermine the usefulness of XSD in the first place. > So I'm sensing there may be some opposition to this, given that namespacing > isn't widely used in the existing RESTful APIs. I guess I'm wondering > whether this ommission was a concious decision, or just that nobody saw the > need for using namespaces but wouldn't be averse to their use in principle. I think that XSD is a bigger mistake than namespaces, though namespaces have their set of annoyances. If you go REST I would suggest to avoid both, but use Relax-NG as your schemas language. > Obviously there are other RESTful examples out there in the wild where the > xmlns attribute makes an appearance, Atom springs to mind here ... xmlns="http://www.w3.org/2005/Atom">. And I don't need to rehearse the basic > advantages of using namespaces, partitioning the global namespace, aiding in > validation, encoding version information etc. But I would be interested in > hearing if there's determined opposition to their use, and if so what the > reasoning is. In general they make implementations more complex?for example in XPath you will have to register all namespaces before being able to execute a query, it's less readable, etc ... My suggestion would be to use a non-namespaced space and use the namespaces only for custom extensions if the need arise. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel at veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/ From bkearney at redhat.com Fri Apr 30 14:34:13 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Fri, 30 Apr 2010 10:34:13 -0400 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: References: Message-ID: <4BDAEA65.6030400@redhat.com> On 04/29/2010 06:55 AM, Eoghan Glynn wrote: > > Folks, > > I wanted to get the group's feeling for the use of namespaces in > representation types. > > The context for the question initially comes from a discussion about how > action/operations were to be modelled in RHEVM-API, particularly how to > capture the action-specific parameter types in the schema. In XML schema > terms, my first cut was to use an xs:any within the action element, but > to restrict the contained type to the local namespace. Which of course > requires that a target namespace is defined in the first place. > > So I'm sensing there may be some opposition to this, given that > namespacing isn't widely used in the existing RESTful APIs. I guess I'm > wondering whether this ommission was a concious decision, or just that > nobody saw the need for using namespaces but wouldn't be averse to their > use in principle. > > Obviously there are other RESTful examples out there in the wild where > the xmlns attribute makes an appearance, Atom springs to mind here ... > . And I don't need to rehearse > the basic advantages of using namespaces, partitioning the global > namespace, aiding in validation, encoding version information etc. But I > would be interested in hearing if there's determined opposition to their > use, and if so what the reasoning is. > > Thanks, > Eoghan > > > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices I would be all for namespaces for links and actions As long as it does not make the json marshalling wonky. I saw some example where the json for was foo: {@bar="12} which is wonky. -- bk From bkearney at redhat.com Fri Apr 30 14:34:37 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Fri, 30 Apr 2010 10:34:37 -0400 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: <20100430141924.GK32184@redhat.com> References: <20100430141924.GK32184@redhat.com> Message-ID: <4BDAEA7D.4010501@redhat.com> On 04/30/2010 10:19 AM, Daniel Veillard wrote: > On Thu, Apr 29, 2010 at 11:55:07AM +0100, Eoghan Glynn wrote: >> Folks, >> >> I wanted to get the group's feeling for the use of namespaces in >> representation types. >> >> The context for the question initially comes from a discussion about how >> action/operations were to be modelled in RHEVM-API, particularly how to >> capture the action-specific parameter types in the schema. In XML schema >> terms, my first cut was to use an xs:any within the action element, but to >> restrict the contained type to the local namespace. Which of course requires >> that a target namespace is defined in the first place. > > Why XML Schemas ? Why not Relax-NG instead. > As an implementor, I *strongly* suggest to avoid XSD unless for very > very simple things. And even very simple thing are described in very > painful terms with no formal semantic. No later than today I had to dig > in > http://www.w3.org/TR/xmlschema-1/#Simple_Type_Definition_details > for some other Red Hat employees requesting help. This thing is horrid > please avoid it. > In contrast Relax-NG specification is 1/ clear 2/ includes a formal > semantic description 3/ has more expressive power than XSD and is > even an ISO standard. > http://www.oasis-open.org/committees/relax-ng/spec-20011203.html > > Actually I would be very surprised if there wasn't a way to use > xs:any allowing only non-namespaced elements, but considering the > lack of clarity of the spec, no matter everybody gets confused. In > the end people just try with the set of implementation tehy target > and don't try to understand the real expected semantic of their schemas, > which IMHO completely undermine the usefulness of XSD in the first > place. > >> So I'm sensing there may be some opposition to this, given that namespacing >> isn't widely used in the existing RESTful APIs. I guess I'm wondering >> whether this ommission was a concious decision, or just that nobody saw the >> need for using namespaces but wouldn't be averse to their use in principle. > > I think that XSD is a bigger mistake than namespaces, though > namespaces have their set of annoyances. If you go REST I would > suggest to avoid both, but use Relax-NG as your schemas language. > >> Obviously there are other RESTful examples out there in the wild where the >> xmlns attribute makes an appearance, Atom springs to mind here ...> xmlns="http://www.w3.org/2005/Atom">. And I don't need to rehearse the basic >> advantages of using namespaces, partitioning the global namespace, aiding in >> validation, encoding version information etc. But I would be interested in >> hearing if there's determined opposition to their use, and if so what the >> reasoning is. > > In general they make implementations more complex?for example in > XPath you will have to register all namespaces before being able to > execute a query, it's less readable, etc ... > My suggestion would be to use a non-namespaced space and use the > namespaces only for custom extensions if the need arise. > > Daniel > I do agreee... RelaxNG is much easier to read/write. -- bk From eglynn at redhat.com Fri Apr 30 15:06:24 2010 From: eglynn at redhat.com (Eoghan Glynn) Date: Fri, 30 Apr 2010 16:06:24 +0100 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: <20100430141924.GK32184@redhat.com> References: <20100430141924.GK32184@redhat.com> Message-ID: <1272639984.3698.329.camel@quark> On Fri, 2010-04-30 at 16:19 +0200, Daniel Veillard wrote: > On Thu, Apr 29, 2010 at 11:55:07AM +0100, Eoghan Glynn wrote: > > Folks, > > > > I wanted to get the group's feeling for the use of namespaces in > > representation types. > > > > The context for the question initially comes from a discussion about how > > action/operations were to be modelled in RHEVM-API, particularly how to > > capture the action-specific parameter types in the schema. In XML schema > > terms, my first cut was to use an xs:any within the action element, but to > > restrict the contained type to the local namespace. Which of course requires > > that a target namespace is defined in the first place. > > Why XML Schemas ? Why not Relax-NG instead. Yeah, I'd love to learn RELAX NG properly. However on the RHEVM-API project we've codegen'd the JAXB model from schema, and unfortunately the JAXB compiler's support for RNG is marked "(experimental,unsupported)" so I'd be a bit nervous about relying on it. Cheers, Eoghan From bburke at redhat.com Fri Apr 30 19:42:20 2010 From: bburke at redhat.com (Bill Burke) Date: Fri, 30 Apr 2010 15:42:20 -0400 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: <1272639984.3698.329.camel@quark> References: <20100430141924.GK32184@redhat.com> <1272639984.3698.329.camel@quark> Message-ID: <4BDB329C.70600@redhat.com> Eoghan Glynn wrote: > On Fri, 2010-04-30 at 16:19 +0200, Daniel Veillard wrote: >> On Thu, Apr 29, 2010 at 11:55:07AM +0100, Eoghan Glynn wrote: >>> Folks, >>> >>> I wanted to get the group's feeling for the use of namespaces in >>> representation types. >>> >>> The context for the question initially comes from a discussion about how >>> action/operations were to be modelled in RHEVM-API, particularly how to >>> capture the action-specific parameter types in the schema. In XML schema >>> terms, my first cut was to use an xs:any within the action element, but to >>> restrict the contained type to the local namespace. Which of course requires >>> that a target namespace is defined in the first place. >> Why XML Schemas ? Why not Relax-NG instead. > > > Yeah, I'd love to learn RELAX NG properly. > FYI, AFAIK, there is not JAXB support for Relax NG. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From veillard at redhat.com Fri Apr 30 20:29:28 2010 From: veillard at redhat.com (Daniel Veillard) Date: Fri, 30 Apr 2010 22:29:28 +0200 Subject: [rest-practices] Namespace qualifying respresentation types In-Reply-To: <4BDB329C.70600@redhat.com> References: <20100430141924.GK32184@redhat.com> <1272639984.3698.329.camel@quark> <4BDB329C.70600@redhat.com> Message-ID: <20100430202928.GQ32184@redhat.com> On Fri, Apr 30, 2010 at 03:42:20PM -0400, Bill Burke wrote: > > > Eoghan Glynn wrote: > >On Fri, 2010-04-30 at 16:19 +0200, Daniel Veillard wrote: > >>On Thu, Apr 29, 2010 at 11:55:07AM +0100, Eoghan Glynn wrote: > >>>Folks, > >>> > >>>I wanted to get the group's feeling for the use of namespaces in > >>>representation types. > >>> > >>>The context for the question initially comes from a discussion about how > >>>action/operations were to be modelled in RHEVM-API, particularly how to > >>>capture the action-specific parameter types in the schema. In XML schema > >>>terms, my first cut was to use an xs:any within the action element, but to > >>>restrict the contained type to the local namespace. Which of course requires > >>>that a target namespace is defined in the first place. > >> Why XML Schemas ? Why not Relax-NG instead. > > > > > >Yeah, I'd love to learn RELAX NG properly. > > > > FYI, AFAIK, there is not JAXB support for Relax NG. http://java.sun.com/developer/technicalArticles/WebServices/jaxb/ Why W3C XML Schema Language? "the XML Schema Language is much richer than DTDs" there is actually some reasons why RNG would not suit perfectly, it's actually way too versatile, and doesn't necessarilly have an unique content model for each element, but what an answer ! :-) Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel at veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/