rest/rex-proposal: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(typos, integrate Dimitri's changes)
Line 1: Line 1:
= DUHPER: A Dual-Use HTML Profile Expressing REST =
= DUHPER: A Dual-Use HTML Profile Expressing REST =
== The 0.8% Solution for Web Services ==
== The 0.8% Solution for Web Services ==
=== aka XOXR ("Shocker"): eXtensible Open XHTML-REST ==
==== October 18th, 2005 ====
==== October 18th, 2005 ====
"Something better than a diaper-soundex" naming content: XOX-REST = XOXR (SHOCKER)


= Web Services: The Opportunity =
= Web Services: The Opportunity =
Line 42: Line 42:
;Discoverability: No standard way to find services
;Discoverability: No standard way to find services
;Interoperability: Too many incompatible ways to encode links, data
;Interoperability: Too many incompatible ways to encode links, data
;Extensability: What if your schema isn't 100% right?
;Extensibility: What if your schema isn't 100% right?
;Comprehensability: What the heck does "state transfer" mean?
;Comprehensibility: What the heck does "state transfer" mean?


= Proposal: A Dual-Use (X)HTML Profile =
= Proposal: A Dual-Use (X)HTML Profile =
Line 68: Line 68:


= What Are Microformats? =
= What Are Microformats? =
* simple social conventions (rel="proflie")
* simple social conventions (rel="profile")
* using existing tags or brief CSS class names
* using existing tags or brief CSS class names
* to encode machine-readable semantics
* to encode machine-readable semantics
Line 77: Line 77:
* Link annotation, e.g.:
* Link annotation, e.g.:
** RelTag (Technorati): <a rel="tag" href=...>
** RelTag (Technorati): <a rel="tag" href=...>
** RelNoFollow (Gooogle):  <a rel="nofollow" href=...>
** RelNoFollow (Google):  <a rel="nofollow" href=...>
* User data
* User data
** [http://microformats.org/wiki/hcard hCard] (based on [http://www.ietf.org/rfc/rfc2426.txt vCard])
** [http://microformats.org/wiki/hcard hCard] (based on [http://www.ietf.org/rfc/rfc2426.txt vCard])
Line 100: Line 100:
   <dt>Key #1<dt>
   <dt>Key #1<dt>
   <dd><ol> <-- Array -->
   <dd><ol> <-- Array -->
         <li>subitem #1</li>
         <li>sub-item #1</li>
         <li>subitem #2</li>
         <li>sub-item #2</li>
   </ol></dd>
   </ol></dd>
  </dl>
  </dl>


= Challenge #2: Only Two Verbs =
= Challenge #2: Only Two Verbs =
* Overload URI with actions? No!
;Overload URI with actions? No!
* Web 2.0 is an constructive medium
: Web 2.0 is an constructive medium
* Don't store a document: ask for creation
;Don't store a document; ask for creation
** POST parent&key1=value1 => child URI
: POST parent&key1=value1 => child URI
* Don't edit document: create new revision
;Don't overwrite documents; update
** The concept of bottomless stack: each document is also a collection of its revisions, with the latest revision sitting at the top of the stack. After the number of revisions reaches the arbitrary size of the stack, oldest revisions fall off the stack into oblivion (note: size=1 and size=0 are possible, too)
: POST child&key1=value1 => new child URI
* Don't delete a document: flag for removal
;Don't delete a document; flag for removal
** POST child&shouldDelete=true
: POST child&shouldDelete=true


= Challenge #3: Key-Value Data =
= Challenge #3: Key-Value Data =

Revision as of 18:11, 18 October 2005

DUHPER: A Dual-Use HTML Profile Expressing REST

The 0.8% Solution for Web Services

= aka XOXR ("Shocker"): eXtensible Open XHTML-REST

October 18th, 2005

Web Services: The Opportunity

  • "The Next Big Thing"
  • Rewriting the web as a platform
  • Foundation of [Web 2.0] businesses
    • Architecture of participation
    • Infrastructure for collaboration
  • Enterprise App Integration (EAI) all over again

Web Services: The Problem

  • Can work really well when you have:
    • Well-defined community
    • Well-run governance
    • Well-understood problem space
  • Not true of the public Internet
  • Not true of most vertical industries

The Answer(?): REST vs. RPC

  • 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

  • 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
Extensibility
What if your schema isn't 100% right?
Comprehensibility
What the heck does "state transfer" mean?

Proposal: A Dual-Use (X)HTML Profile

  • Subset of REST that works with browsers
    • XHTML Basic vs. arbitrary XML
    • Just GET & POST (not PUT or DELETE)
    • Encode URIs in hyperlinks (<a href>) and forms (<form action>)
    • Inputs always key-value pairs (like database table)
  • With CSS and AJAX, can be the website
    • DRY = Don't Repeat Yourself
    • Makes discovery and documentation trivial

Three Challenges

  • Is HTML Machine-Parseable?
  • Are there really only two verbs?
  • Can you build real apps on key-value encoding?

Challenge #1: Machine-Parseability

  • Screen scraping all over again? No!
  • Use the "secret sauce" of "semantic salt"
    • cf. "syntactic sugar" -- hides unpleasant details
    • "semantic salt" -- brings out latent structure
  • In other words, "microformats"

What Are Microformats?

  • simple social conventions (rel="profile")
  • using existing tags or brief CSS class names
  • to encode machine-readable semantics
  • in human-readable HTML, XHTML, or even XML
    • cf. <link rel> in Atom

Kinds of Microformats

  • Link annotation, e.g.:
    • RelTag (Technorati): <a rel="tag" href=...>
    • RelNoFollow (Google): <a rel="nofollow" href=...>
  • User data
  • Data structures
    • XOXO lists: ol, ul, dl
    • XOXT tables: th, tr, td

Example: hCard

  • hCard class names := vCard fields
<div class="vcard">
 <a class="url fn" href="http://tantek.com/">
  Tantek Çelik
 </a>
 <div class="org">Technorati</div>
</div>

Example: eXtensible Open XHTML Outlines

  • Reuse existing HTML tags
  • Arbitrary data structure (like property lists)
<dl class='xoxo'> <-- Dictionary -->
 <dt>Key #1<dt>
 <dd><ol> <-- Array -->
       <li>sub-item #1</li>
       <li>sub-item #2</li>
 </ol></dd>
</dl>

Challenge #2: Only Two Verbs

Overload URI with actions? No!
Web 2.0 is an constructive medium
Don't store a document; ask for creation
POST parent&key1=value1 => child URI
Don't overwrite documents; update
POST child&key1=value1 => new child URI
Don't delete a document; flag for removal
POST child&shouldDelete=true

Challenge #3: Key-Value Data

  • Encode complex structures as XML text? No!
  • Treat web service like a database
    • Common classes (e.g. users, items, carts) => tables
    • Key-value dictionaries => records
    • URIs for each records => primary keys
  • Need NOT reflect actual internal database
    • Can present a synthetic view
    • But, makes a great starting point (cf. Ruby on Rails

The 0.8% Solution for Web Services

  • (80% of benefit/20% of effort)^3
    • XOXO vs. XML: 80/20
    • GET/POST vs. REST: 80/20 x 80/20 = 64/4
    • Key-Value vs. structured input: 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

Advantages

  • Reuse existing semantics and structure
    • Generally only one way to encode something
  • Reduce possible degrees of freedom
    • Simplifies design, improves interoperability
    • Focus on the 80% where agreement is easy
  • Increase learnability
    • Everyone (in this space) can write it
    • Everything (in the world) can read it
    • The API is the documentation is the format

Implications

  • Is this the "tipping point"?
    • The 'LDAP' of web services?
    • The 'missing link' for REST?
    • The 'killer app' for Ruby on Rails?
  • Why?
    • Looser than XML => allows innovation
    • Tighter than REST => encourages interoperability
    • Simpler than SOAP => enables rapid adoption

For More Information