Difference between revisions of "rest/brainstorming"

From Microformats Wiki
Jump to navigation Jump to search
 
(=== Nouns ===)
Line 1: Line 1:
 +
= XHTML-REST Brainstorming =
 +
 +
This page collects ideas from [[rest-examples]] how to best encode [[REST]] data in an XHTML microformat.
 +
 +
== Constraints ==
 +
 +
The underlying premise of this investigation is that REST is less useful that it could be due to concerns about a) interoperability, and b) discoverability.  To address this, we propose adopting microformat-style conventions to further constrain the ways REST already constrains web services.
 +
 +
In particular, we constrain REST to work with existing web browser clients -- yet also be machine-parseable.  This means:
 +
* All inputs must be url-encoded (or maybe mime/multipart)
 +
* All output must be XHTML, either:
 +
** XOXO: [[xoxo]] (dl, ul, ol)
 +
** XOXT: [[table-brainstorms]] (table-th-tr-td)
 +
* All URI links must be encoded as either:
 +
** Anchors (<a&rt;) (via 'href')
 +
** Forms (<a&rt;) (via 'action')
 +
* Only GET and POST actions are supported
 +
 +
This may seem  very strict, but that's the point: by adding more constraints, we reduce gratuitous degrees of freedom and enable greater consistency.
 +
 +
This may not solve every conceivable problem, but it should handle the 50% case pretty well:
 +
* REST: 80% of web services
 +
* XHTML: 80% of XML expressiveness
 +
* GET/POST + urlencoding: 80% of queries
 +
or, put another way:
 +
* 80% x 80% x 80% = 51.2% of the benefit for
 +
* 20% x 20% x 20% = 0.8% of the effort
 +
 +
== Conventions ==
 +
 +
To make parsing and auto-discovery easier -- and also simplify the design process -- we propose the following additional conventions.
 +
 +
=== Nouns ===
 +
 +
As usual in REST, every ''noun'' must be a URI.  However, we explicitly define four types of URIs:
 +
:root;The base URI for the web service, e.g.: <code>http://example.com/webservice</code>.
 +
:instances;URIs representing individual entities, e.g.: <code>http://example.com/webservice/users/me%40drernie.com</code>.
 +
:factories;The URIs used to create or search for those instances, e.g.: <code>http://example.com/webservice/users</code>.
 +
:singletons;Any URIs instances that are not part of a particular factory, e.g.: <code>http://example.com/webservice/demo</code>.
 +
 +
=== Verbs ===
 +
 +
 +
== Questions for further research ==
 +
 +
# How to specify whether a field is optional or required?
 +
 +
== Patterns ==
 +
 +
=== Anchor Design Pattern ===
 +
 +
&lt;a class="deth" href="http//somesite.com/prog/adduser">label&lt;/a>
 +
 +
=== Forms Design Pattern ===
 +
 +
 +
== See Also ==
 +
 +
* [http://www.opendarwin.org/~drernie/rest-api.html REST self-describing API proposal]
 +
* [http://opensearch.a9.com/ OpenSearch search results standard (REST-like)]
 +
* [[rest-brainstorming]]
  
 
[http://www.opendarwin.org/~drernie/rest-api.html Proposed REST API]
 
[http://www.opendarwin.org/~drernie/rest-api.html Proposed REST API]

Revision as of 19:50, 13 October 2005

XHTML-REST Brainstorming

This page collects ideas from rest/examples how to best encode REST data in an XHTML microformat.

Constraints

The underlying premise of this investigation is that REST is less useful that it could be due to concerns about a) interoperability, and b) discoverability. To address this, we propose adopting microformat-style conventions to further constrain the ways REST already constrains web services.

In particular, we constrain REST to work with existing web browser clients -- yet also be machine-parseable. This means:

  • All inputs must be url-encoded (or maybe mime/multipart)
  • All output must be XHTML, either:
  • All URI links must be encoded as either:
    • Anchors (<a&rt;) (via 'href')
    • Forms (<a&rt;) (via 'action')
  • Only GET and POST actions are supported

This may seem very strict, but that's the point: by adding more constraints, we reduce gratuitous degrees of freedom and enable greater consistency.

This may not solve every conceivable problem, but it should handle the 50% case pretty well:

  • REST: 80% of web services
  • XHTML: 80% of XML expressiveness
  • GET/POST + urlencoding: 80% of queries

or, put another way:

  • 80% x 80% x 80% = 51.2% of the benefit for
  • 20% x 20% x 20% = 0.8% of the effort

Conventions

To make parsing and auto-discovery easier -- and also simplify the design process -- we propose the following additional conventions.

Nouns

As usual in REST, every noun must be a URI. However, we explicitly define four types of URIs:

root;The base URI for the web service, e.g.: http://example.com/webservice.
instances;URIs representing individual entities, e.g.: http://example.com/webservice/users/me%40drernie.com.
factories;The URIs used to create or search for those instances, e.g.: http://example.com/webservice/users.
singletons;Any URIs instances that are not part of a particular factory, e.g.: http://example.com/webservice/demo.

Verbs

Questions for further research

  1. How to specify whether a field is optional or required?

Patterns

Anchor Design Pattern

<a class="deth" href="http//somesite.com/prog/adduser">label</a>

Forms Design Pattern

See Also

Proposed REST API