Please read: http://zacstewart.com/2012/04/14/http-options-method.html and http://news.ycombinator.com/item?id=3841710 Very good stuff.
The JavaScript library I am using, Jersey, automatically returns something called WADL on OPTION requests. Nothing as specific as this blog suggests, though. After reading the last chapter about hypermedia clients, I have been thinking about rendering the documentation on a GET request with an "Accept: text/html" header. That would also force me to keep the documentation close to the code. A number of resources could even be accessible through HTML forms... Regards, Joost -- Joost Cassee http://joost.cassee.net Op 15 apr. 2012 17:00 schreef "Martin Wawrusch" <martin@wawrusch.com> het volgende: > Please read: http://zacstewart.com/2012/04/14/http-options-method.html > and http://news.ycombinator.com/item?id=3841710 > > Very good stuff. >
At first I thought this was a good idea. But I've tried to apply this idea in REST and it was conflicting about what I've read on it. My reflexion is that it is not needed as proposed. Yes OPTIONS have its uses, but not as a WADL. Here is my comment: http://zacstewart.com/2012/04/14/http-options-method.html#comment-498328291 On Sun, Apr 15, 2012 at 12:07 PM, Joost Cassee <joost@cassee.net> wrote: > The JavaScript library I am using, Jersey, automatically returns something > called WADL on OPTION requests. Nothing as specific as this blog suggests, > though. > > After reading the last chapter about hypermedia clients, I have been > thinking about rendering the documentation on a GET request with an "Accept: > text/html" header. That would also force me to keep the documentation close > to the code. A number of resources could even be accessible through HTML > forms... > > Regards, > Joost > > -- > Joost Cassee > http://joost.cassee.net > > Op 15 apr. 2012 17:00 schreef "Martin Wawrusch" <martin@wawrusch.com> het > volgende: > >> Please read: http://zacstewart.com/2012/04/14/http-options-method.html >> and http://news.ycombinator.com/item?id=3841710 >> >> Very good stuff.
Differents opinions about needing or not a contract when using REST. http://www.infoq.com/news/2007/06/rest-description-language On Sun, Apr 15, 2012 at 2:35 PM, Philippe Rathé <prathe@gmail.com> wrote: > At first I thought this was a good idea. But I've tried to apply this > idea in REST and it was conflicting about what I've read on it. My > reflexion is that it is not needed as proposed. Yes OPTIONS have its > uses, but not as a WADL. > > Here is my comment: > http://zacstewart.com/2012/04/14/http-options-method.html#comment-498328291 > > > On Sun, Apr 15, 2012 at 12:07 PM, Joost Cassee <joost@cassee.net> wrote: >> The JavaScript library I am using, Jersey, automatically returns something >> called WADL on OPTION requests. Nothing as specific as this blog suggests, >> though. >> >> After reading the last chapter about hypermedia clients, I have been >> thinking about rendering the documentation on a GET request with an "Accept: >> text/html" header. That would also force me to keep the documentation close >> to the code. A number of resources could even be accessible through HTML >> forms... >> >> Regards, >> Joost >> >> -- >> Joost Cassee >> http://joost.cassee.net >> >> Op 15 apr. 2012 17:00 schreef "Martin Wawrusch" <martin@wawrusch.com> het >> volgende: >> >>> Please read: http://zacstewart.com/2012/04/14/http-options-method.html >>> and http://news.ycombinator.com/item?id=3841710 >>> >>> Very good stuff.
Very interesting stuff. Thanks for posting! Regards, Joost 2012/4/15 Philippe Rathé <prathe@gmail.com>: > Differents opinions about needing or not a contract when using REST. > http://www.infoq.com/news/2007/06/rest-description-language > > On Sun, Apr 15, 2012 at 2:35 PM, Philippe Rathé <prathe@gmail.com> wrote: >> At first I thought this was a good idea. But I've tried to apply this >> idea in REST and it was conflicting about what I've read on it. My >> reflexion is that it is not needed as proposed. Yes OPTIONS have its >> uses, but not as a WADL. >> >> Here is my comment: >> http://zacstewart.com/2012/04/14/http-options-method.html#comment-498328291 >> >> >> On Sun, Apr 15, 2012 at 12:07 PM, Joost Cassee <joost@cassee.net> wrote: >>> The JavaScript library I am using, Jersey, automatically returns something >>> called WADL on OPTION requests. Nothing as specific as this blog suggests, >>> though. >>> >>> After reading the last chapter about hypermedia clients, I have been >>> thinking about rendering the documentation on a GET request with an "Accept: >>> text/html" header. That would also force me to keep the documentation close >>> to the code. A number of resources could even be accessible through HTML >>> forms... >>> >>> Regards, >>> Joost >>> >>> -- >>> Joost Cassee >>> http://joost.cassee.net >>> >>> Op 15 apr. 2012 17:00 schreef "Martin Wawrusch" <martin@wawrusch.com> het >>> volgende: >>> >>>> Please read: http://zacstewart.com/2012/04/14/http-options-method.html >>>> and http://news.ycombinator.com/item?id=3841710 >>>> >>>> Very good stuff. -- Joost Cassee http://joost.cassee.net
I'd been considering writing about WADL, and I think this thread signifies that I should bump it up in my queue. Philippe, that post you linked to is awesome, and sums up my feelings nicely. Joost, your comments about HTML mirror why I like using XTHML as a media type for my API directly, actually... Martin, thanks for the link!
You are welcome. Not sure which approach is the best (or even working) but the OPTIONS one grows on me a bit but I think there might be speed bumps ahead. Perhaps a combination of OPTIONS + Philippe's approach is the right way. @Philippe If you haven't take a look at: http://www.odata.org/blog/2010/4/22/queryable-odata-metadata Microsoft's odata seems to use a similar approach to retrieving meta data. @Steve Great that you move WADL up your queue. Here are some WADL descriptions for popular APIs: https://github.com/apigee/wadl-library . You might also want to look into Google's competing JSON schema based discovery format (https://developers.google.com/discovery/). In general I see WADL and the others as supplemental to hypermedia interfaces. They supply information that would otherwise simply not be available like Google's discovery service does with Oauth2 scopes. Another good use case for this kind of information is to be able to discover what an API is all about through meta data. It is just important to understand that the API, as described at one point in time through meta data might have changed so the clients must follow hypermedia first, meta data second. Cheers Martin On Mon, Apr 16, 2012 at 11:18 AM, Steve Klabnik <steve@steveklabnik.com>wrote: > I'd been considering writing about WADL, and I think this thread > signifies that I should bump it up in my queue. Philippe, that post > you linked to is awesome, and sums up my feelings nicely. > > Joost, your comments about HTML mirror why I like using XTHML as a > media type for my API directly, actually... > > Martin, thanks for the link! >
It seems that it would be possible to endlessly debate on "Does REST needs an IDL?". I have noticed that arguments in favor of an IDL were motivated by practical, historical and business thoughts and arguments against were motivated by theoretical thoughts. I have more questions than answers though. Something that light me up is when I remembered that AtomPub has a service document. Isn't it AtomPub respecting REST? Is there something different about AtomPub service document being identified by a media-type (atomserv+xml) and the protocol not saying anything about how this document should be discovered? It seems that a REST API which is entirely consumed through the reach a client (let's say a browser) does not need a WADL because only transitions are relevant to its user and the client implementation allow them what they want. That may be because those clients implementations honor REST. But business that are encouraging any kind of clients implementations, such as using curl, because they failed to provide them are more, with the user, focused on the raw data itself that could be consumed outside the client that retrieve them. "Most "REST" APIs are less RESTful than HTML pages built on top of them" It can be said like that. I found this quote on http://news.ycombinator.com/item?id=3841710 Another question I have is how an API which uses AtomPub mainly for its collections would present a WADL concerning those collections? Should a WADL repeats already what are in RFCs. If not how they do that? Because the original message of that thread was about OPTIONS, I found an example as to how to use OPTIONS is suggested by Erik Wilde in the case someone would like to support PATCH using AtomPub. http://dret.typepad.com/dretblog/2012/03/patching-atompub.html @Martin: Thanks for bringing this topic. I read the post you point me to. I don't know what to think about oData. It says it provides more capabilities than AtomPub. I'll have to come back to it. On Mon, Apr 16, 2012 at 4:21 PM, Martin Wawrusch <martin@wawrusch.com> wrote: > You are welcome. > > Not sure which approach is the best (or even working) but the OPTIONS one > grows on me a bit but I think there might be speed bumps ahead. Perhaps a > combination of OPTIONS + Philippe's approach is the right way. > > @Philippe If you haven't take a look at: > http://www.odata.org/blog/2010/4/22/queryable-odata-metadata Microsoft's > odata seems to use a similar approach to retrieving meta data. > > @Steve Great that you move WADL up your queue. Here are some > WADL descriptions for popular APIs: > https://github.com/apigee/wadl-library . You might also want to look into > Google's competing JSON schema based discovery format > (https://developers.google.com/discovery/). > > In general I see WADL and the others as supplemental to hypermedia > interfaces. They supply information that would otherwise simply not be > available like Google's discovery service does with Oauth2 scopes. Another > good use case for this kind of information is to be able to discover what an > API is all about through meta data. > > It is just important to understand that the API, as described at one point > in time through meta data might have changed so the clients must follow > hypermedia first, meta data second. > > > Cheers > Martin > > On Mon, Apr 16, 2012 at 11:18 AM, Steve Klabnik <steve@steveklabnik.com> > wrote: >> >> I'd been considering writing about WADL, and I think this thread >> signifies that I should bump it up in my queue. Philippe, that post >> you linked to is awesome, and sums up my feelings nicely. >> >> Joost, your comments about HTML mirror why I like using XTHML as a >> media type for my API directly, actually... >> >> Martin, thanks for the link! > > >
> It seems that it would be possible to endlessly debate on "Does REST > needs an IDL?". But how would the internet function without endless debate? *grin* > I have noticed that arguments in favor of an IDL were > motivated by practical, historical and business thoughts and arguments > against were motivated by theoretical thoughts. I don't know, I'd argue that most APIs don't use an IDL, which is practical, historical, and ... business...y. > Something that light me up is when I remembered that AtomPub has a > service document. Isn't it AtomPub respecting REST? Is there something > different about AtomPub service document being identified by a > media-type (atomserv+xml) and the protocol not saying anything about > how this document should be discovered? Honestly, I haven't dealt with the depths of AtomPub. It's now on my to-do list...