rest/description: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (Reverted edits by TrcavArpas (Talk) to last version by AmeerDawood)
 
(26 intermediate revisions by 9 users not shown)
Line 8: Line 8:


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):
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):
* information is provided via HTML
 
* inputs are always key-value pairs of strings (except for file uploads)
===REST Service Description Conventions===
* only hyperlinks that share the same root are part of the REST service
# information is always returned as (X)HTML hypertext
* there must be a way to discover all valid queries starting from the first link
# inputs are always key-value pairs of strings (except for file uploads)
* forms MUST specify correct actions (e.g., PUT, DELETE), even if the actual implementation uses JavaScript
#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) ==
== Implementations (Twill) ==
Line 23: Line 36:
;formclear <form_id>: resets all the fields in a form
;formclear <form_id>: resets all the fields in a form


In particular, Twill information in the following format:
In particular, Twill retrieves information in the following format:
  >> showforms
  >> showforms
  Form #1
  Form #1
Line 30: Line 43:
       password    password  (None)
       password    password  (None)
       confirm      checkbox  (None)      [] of ['yes']
       confirm      checkbox  (None)      [] of ['yes']
       colour       radio    (None)      [] of ['green', 'blue', 'brown', 'ot ...
       color       radio    (None)      [] of ['green', 'blue', 'brown', 'ot ...
       size        select    (None)      ['Medium (10")'] of ['Tiny (4")', 'S ...
       size        select    (None)      ['Medium (10")'] of ['Tiny (4")', 'S ...
       toppings    select    (None)      ['cheese'] of ['cheese', 'pepperoni' ...
       toppings    select    (None)      ['cheese'] of ['cheese', 'pepperoni' ...
Line 45: Line 58:
;[http://selenium.thoughtworks.com/index.html Selenium]: JavaScript framework for browser/Plone testing
;[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.
;[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])

Latest revision as of 21:51, 20 December 2008

REST Service Description Conventions (RSDC)

The general consensus (as articulated by Roy and Mark, though disputed by 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

  1. information is always returned as (X)HTML hypertext
  2. inputs are always key-value pairs of strings (except for file uploads)
  3. there must be a way to discover all valid queries starting from the base URI
  4. forms MUST specify correct actions (e.g., PUT, DELETE), even if the actual implementation uses JavaScript

plus

  1. only hyperlinks that share the same root refer to part of the REST service
  2. 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).

Update - Google's sitemap has now been accepted as an industry standard.

Implementations (Twill)

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 web testing article, which also discusses:

Python Browser Poseur (PBP)
by Cory Dodt (came first)
Beautiful Soup
a third-party HTML parsing tool
Quixote
a nice, small Pythonic web framework
John J. Lee's websearch tools
mechanize (inspired by Perl), ClientForm, and ClientCookie
pyparsing
object-oriented text processing
Selenium
JavaScript framework for browser/Plone testing
Agile Testing blog
by Grig Gheorghiu.

Proposals/Examples