rest/brainstorming: Difference between revisions
No edit summary |
(=== 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 === | |||
<a class="deth" href="http//somesite.com/prog/adduser">label</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:
- 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.:
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
- 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>