rest/description

2008-12-20T00:38:33Z

TrcavArpas: eltcaoloac

alnochi
= REST Service Description Conventions (RSDC) =

The general consensus (as articulated by [http://groups.yahoo.com/group/rest-discuss/message/5394 Roy] and [http://groups.yahoo.com/group/rest-discuss/message/5391 Mark], though disputed by [http://groups.yahoo.com/group/rest-discuss/message/5404?threaded=1 others]) is that REST does not need a WSDL-style description language. After all, we use the web without requiring directions, right?

At the same time, there is still confusion about what actually works, and how.

== Brainstorming ==

In at least the Microformats case ("REX") where you're assuming a browser, we can presumably get by with the following constraints (in addition to REST itself, of course; e.g., properly-formed URIs):

===REST Service Description Conventions===
# information is always returned as (X)HTML hypertext
# inputs are always key-value pairs of strings (except for file uploads)
#there must be a way to discover all valid queries starting from the base URI
# forms MUST specify correct actions (e.g., PUT, DELETE), even if the actual implementation uses JavaScript
plus
# only hyperlinks that share the same root refer to part of the REST service
# body text associated with a control/hyperlink provides the human-readable description

=== Sitemaps? ===

Arguably a sitemap is one way of presenting a list of the resources available on particular site, even if it isn't quite the same as a recipe for URL construction (which arguably is more useful in this context).

* [https://www.google.com/webmasters/sitemaps/docs/en/protocol.html Google Sitemap Protocol]
* [http://www.xml.com/pub/a/2005/04/06/restful.html Constructing vs. Traversing URIs]

:Update - Google's sitemap has now been accepted as an [http://www.sitemaps.org/ industry standard].

== Implementations (Twill) ==
[http://darcs.idyll.org/%7Et/projects/twill/README.html twill] is a web app testing language by Titus Brown that functions like a smart REST client!

"Twill is especially good at retrieving and submitting web forms. The form-related feature uses the [following] commands:"
;showforms: shows the forms contained in a web page. Unnamed forms get an ordinal number to use as a form ID
;formvalue <form_id> <name> <value>: fills a field of the specified form with a given value
;submit <button_id>: lets you press a Submit button, thus submitting the form
;formclear <form_id>: resets all the fields in a form

In particular, Twill retrieves information in the following format:
>> showforms
Form #1
## __Name______ __Type___ __ID________ __Value__________________
name text (None)
password password (None)
confirm checkbox (None) [] of ['yes']
color radio (None) [] of ['green', 'blue', 'brown', 'ot ...
size select (None) ['Medium (10")'] of ['Tiny (4")', 'S ...
toppings select (None) ['cheese'] of ['cheese', 'pepperoni' ...
time hidden (None) 1118768019.17
1 submit (None) Submit

Those comment were extracted from ONLamp's [http://www.onlamp.com/lpt/a/6298 web testing] article, which also discusses:
;[http://pbp.berlios.de/ Python Browser Poseur (PBP)]: by Cory Dodt (came first)
;[http://www.crummy.com/software/BeautifulSoup Beautiful Soup]: a third-party HTML parsing tool
;[http://www.mems-exchange.org/software/quixote/ Quixote]: a nice, small Pythonic web framework
;John J. Lee's [http://wwwsearch.sourceforge.net/ websearch] tools:mechanize (inspired by Perl), ClientForm, and ClientCookie
;[http://pyparsing.sourceforge.net/ pyparsing]: object-oriented text processing
;[http://selenium.thoughtworks.com/index.html Selenium]: JavaScript framework for browser/Plone testing
;[http://agiletesting.blogspot.com/2005/02/articles-and-tutorials.html Agile Testing] blog: by Grig Gheorghiu.

== Proposals/Examples ==
* [[rest/microformat-pub-protocol]] by toydi
* [http://pezra.barelyenough.org/blog/2008/01/restful-service-discovery-and-description/ RESTful Service Discovery and Description]
* Atom [http://www-128.ibm.com/developerworks/library/x-atompp1/ Service Documents] (was [http://www.sixapart.com/developers/atom/protocol/atom_introspection.html Introspection])
** Chapter 8 of the [http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-11.txt Atom Publishing Protocol]
* [http://bitworking.org/rfc/draft-gregorio-07.html#rfc.section.5.1 introspection] in the AtomAPI, by Joe Gregorio
* [http://www.xml.com/pub/a/2005/04/06/restful.html Constructing or Traversing URIs?] by Joe Gregorio
* [http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-00.txt URI Templates] by Joe Gregorio
* [https://wadl.dev.java.net/ WADL] - Web Application Description Language, by Marc Hadley
* REST [http://blog.tomayac.de/index.php?date=2007-06-14&time=15:06:52&perma=REST+Describe+%26+Comp.html Describe & Compile] using [http://tomayac.de/rest-describe/latest/RestDescribe.html REST Describe] parser
* REST Contracts [http://www.innoq.com/blog/st/2007/07/26/governance_and_rest.html and "Governance"]
* [http://blogs.sun.com/bblfish/entry/restful_semantic_web_services Restful semantic web services] (in the context of [http://en.wikipedia.org/wiki/SPARQL SPARQL])

Microformats Wiki - User contributions [en]

rest/description