rest-proposal-preso

XHTML-REST

The purpose of this presentation is to describe and justify a proposal for using microformants to constrain REST implementations.

Web Services: RPC vs. REST

• RPC: Remote Procedure Calls
  • URIs are method names
  • XML is the arguments format
  • Implemented in XML-RPC and SOAP
• REST: Representational State Transfer
  • Nouns are URIs, verbs are HTTP: GET, PUT, POST, DELETE
  • XML documents are state information
  • Implemented at Atom, Amazon (sorta)

Advantages of REST over RPC/SOAP

• Much simpler to design
  • Easy to identify appropriate nouns
  • Don't need to define methods (verbs)
  • Don't need a complete object model
• Easier to learn/invoke
  • Always know what a URI means
  • Need not 'tunnel' XML inside XML

Challenges of REST

Discoverability

No standard way to find services

Interoperability

Too many incompatible ways to encode links, data

Extensability

What if your schema isn't 100% right?

Comprehensability

What the heck does "state transfer" mean?

Solution, Part I-A: XHTML

• Use XHTML Basic instead of XML
• Don't need a rigid schema
• No namespaces; free to extend as needed
• Everyone (in this space) can write it
• Everything (in the world) can read it

Solution, Part I-B: XHTML Microformats

• microformats: Add 'semantic salt' to XHTML
  • Annotate existing XHTML tags with meaning
  • Machine-parseable yet human-readable
• Links as <a href=> and <form action=>
• Lists as XOXO: eXtensible Open XHTML Outlines
  • ol, dl, ul
  • Work like Mac OS X property lists

Solution, Part II: Browser clients

• Makes testing & documentation trivial
  • The API is the documentation is the format
• Use subset of REST supported by browsers
  • GET http://host/uri
  • GET http://host/uri?query=string...
  • POST http://host/uri?key=value...
• encode input data in urls, not XML docs

Solution, Part III-A: Web as database

• CRUD: Create, Retrieve, Update, Delete
• Structured URLs vs. Opaque URIs
  • http://host:port/base/table/record
• Note: need not reflect actual database
  • Synthetic "user model" for public API purposes
  • But, an easy way to start (cf. Ruby on Rails)

Solution, Part III-B: Web as database

• base: defines service
  • GET base?query # search across all tables
• table: collection of URLs with same schema
  • GET table?query # search across this table
  • URIs become primary keys for joins!
• record: individual item, user, cart, etc.
  • POST table?data # update record

Solution, Part III-C: Web as database

• Special conventions
  • GET http://host/uri?view=edit # API as editable forms
  • GET http://host/uri?view=api # API as dt/dd descriptions
  • GET http://host/uri?view=list # key-value as dt/dd
  • GET http://host/uri?view=table # key-value as th/td
• Other verbs become queries
  • POST table?data # create a new record [vs. PUT]
  • POST table?delete=yes # flag for remove [vs. DELETE]

The 0.8% Solution for Web Services

• (80% of benefit/20% of effort)^3
  • XHTML vs. XML: 80/20
  • GET/POST vs. REST: 80/20 x 80/20 = 64/4
  • Database vs. freeform URIs: 80/20 x 64/4 = 51.2/0.8
• Half the benefit for 1% of the effort!
  • Maybe not everything, but the basics easily
  • Power comes from how much you can ignore

Implications

• The 'missing link' for REST?
• The 'killer app' for Ruby on Rails?
• The "tipping point" for web services?
  • Looser than XML => easier compatibility
  • Tighter than REST => better interoperability
  • Simpler than SOAP => greater adoption

Examples (TBD)

• ?view=api (dictionary of valid requests)
• {base,table}?query (OpenSearch)
• base/ (home page)
• table/ (section page)
• table?view=edit (record creation forms)

Examples - Records (TBD)

• record/ (default view)
• record?view=edit (record update)
• record?view=list (dt/dd list)
• record?view=table (th/td row)

But Wait, There's More!

• Not just for web services
  • Do your whole website this way!
  • CSS classes + styles => prettified XHTML
  • Don't Repeat Yourself (DRY): website == API
• Perfect solution for AJAX
  • AJAX: Asynchronous-JavaScript-and-XML
  • Actually, JAH: Just Asynchronous HTML
  • JavaScript loves HTML; fast, only eight lines of code!

For More Information

• Microformats http://microformats.org
  • What are Microformats? http://tantek.com/presentations/2005/06/what-are-microformats/
  • Discussion Lists http://microformats.org/discuss/
  • XOXO: http://microformats.org/wiki/xoxo
• XHTML-REST
  • research: http://microformats.org/wiki/rest-examples
  • blog: http://www.opendarwin.org/~drernie/
  • This presentation: http://microformats.org/wiki/rest-proposal-preso