Microformats Wiki - User contributions [en]

rest/forms-brainstorming

2006-10-09T14:49:39Z

OlaBerg: /* Proposal B: REST-oriented process */

= Forms Brainstorming =

This page collects ideas from [[forms-examples]] how to best encode form data into a microformat

== Proposal A: DETH - Dictionaries Encoding/Transmitting HTML ==

=== Rules (Strawman) ===

# Only use [http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_sformsmodule XHTML Basic Forms] Module
# Must use action with appropriate URI (no scripts)
# Recommend: use a ''label'' with every ''input''
# Make the ''for'' of the ''label'' match the ''id'' of ''input''
# Group ''label'' with ''input'' using ''<dl><dt><dd>''
# Always place ''submit'' and ''reset'' outside grouping

=== Questions for further research ===

# How to specify whether a field is optional or required?

## Suggestion: the label contains a * ?

=== Patterns ===

==== Anchor Design Pattern ====

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

==== Forms Design Pattern ====

<form class="deth" action="http://somesite.com/users" method="post">
<dl>
<dt><label for="firstname">First name:</label></dt>
<dd><input type="text" id="firstname" />
</dd><dt>
<label for="lastname">Last name:</label></dt>
<dd><input type="text" id="lastname" />
</dd><dt>Sex</dt>
<dd><input type="radio" name="sex" value="male">Male</input>
<input type="radio" name="sex" value="female">Female</input>
</dd><dt>Travel</dt>
<dd> <input type="checkbox" name="travel" value="car">Car</input>
<input type="checkbox" name="travel" value="bike">Bicycle</input>
</dd><dt>
<label for="age">Age:</dt>
<dd>
<select>
<option val=0>< 18</option>
<option val=18>18-64</option>
<option val=65>65+</option>
</select>
</dd><dt>
<label for="description">Description:</label></dt>
<dd><textarea id="description">Default text</textarea>
</dd>
</dl>
<input type="submit" value="Send" />
<input type="reset" />
</form>

== Sample Python Binding ==

order=[
"firstname","lastname","sex",'"travel", "age","description"
]
dict={
"@@tag":"form",
"@action":"http://somesite.com/users/",
"@class":"deth",
"@enctype":"application/x-www-form-urlencoded",
"@method":"post",
"@@order":order,
"firstname":"First name:",
"lastname":"Last name:",
"sex":{"@type":"radio", "male":"Male", "female":"Female"},
"travel":{"@type":"checkbox", "car":"Car", "bike":"Bicycle"},
"age":{"@@body":"Age:", "@type":"select",
"0":"< 18", "18":"18-64", "65":"65+"
},
"description":{
"@@body":"Description:",
"@type":"textarea",
"@value":"Default text"
}
}

== Proposal B: REST-oriented process ==
From [Kyle Cordes], for the discovery of the parameters:

* You discover the URL of a service by some means.
* You GET that URL, which returns an HTML form.
* The HTML form describes where to POST to invoke that service, and what
parameters can be passed in that POST. In some cases, it will use
<selects>s to describe what options are valid for a parameter.
* In most cases, the form will be interspersed with human readable text,
to explain the meaning of the parameters (a machine-understandable way
to explain parameter meaning, sounds like an AI problem...)
* You (the user of a web browser, or a piece of software
programmatically using the server) populate the parameters and POST them
to the URL you discovered via the form.
* You get back a response, which might be an error message about a
parameter problem, or might be a respresentation of the "answer".

[OlaBerg] says: This is exactly what I do, and it works great! In fact, I
use it both for POST-API and GET-API. A set of forms defines a REST-ful
API.

== 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]]

rest/forms-brainstorming

2006-10-09T14:46:38Z

OlaBerg: /* Questions for further research */

= Forms Brainstorming =

This page collects ideas from [[forms-examples]] how to best encode form data into a microformat

== Proposal A: DETH - Dictionaries Encoding/Transmitting HTML ==

=== Rules (Strawman) ===

# Only use [http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_sformsmodule XHTML Basic Forms] Module
# Must use action with appropriate URI (no scripts)
# Recommend: use a ''label'' with every ''input''
# Make the ''for'' of the ''label'' match the ''id'' of ''input''
# Group ''label'' with ''input'' using ''<dl><dt><dd>''
# Always place ''submit'' and ''reset'' outside grouping

=== Questions for further research ===

# How to specify whether a field is optional or required?

## Suggestion: the label contains a * ?

=== Patterns ===

==== Anchor Design Pattern ====

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

==== Forms Design Pattern ====

<form class="deth" action="http://somesite.com/users" method="post">
<dl>
<dt><label for="firstname">First name:</label></dt>
<dd><input type="text" id="firstname" />
</dd><dt>
<label for="lastname">Last name:</label></dt>
<dd><input type="text" id="lastname" />
</dd><dt>Sex</dt>
<dd><input type="radio" name="sex" value="male">Male</input>
<input type="radio" name="sex" value="female">Female</input>
</dd><dt>Travel</dt>
<dd> <input type="checkbox" name="travel" value="car">Car</input>
<input type="checkbox" name="travel" value="bike">Bicycle</input>
</dd><dt>
<label for="age">Age:</dt>
<dd>
<select>
<option val=0>< 18</option>
<option val=18>18-64</option>
<option val=65>65+</option>
</select>
</dd><dt>
<label for="description">Description:</label></dt>
<dd><textarea id="description">Default text</textarea>
</dd>
</dl>
<input type="submit" value="Send" />
<input type="reset" />
</form>

== Sample Python Binding ==

order=[
"firstname","lastname","sex",'"travel", "age","description"
]
dict={
"@@tag":"form",
"@action":"http://somesite.com/users/",
"@class":"deth",
"@enctype":"application/x-www-form-urlencoded",
"@method":"post",
"@@order":order,
"firstname":"First name:",
"lastname":"Last name:",
"sex":{"@type":"radio", "male":"Male", "female":"Female"},
"travel":{"@type":"checkbox", "car":"Car", "bike":"Bicycle"},
"age":{"@@body":"Age:", "@type":"select",
"0":"< 18", "18":"18-64", "65":"65+"
},
"description":{
"@@body":"Description:",
"@type":"textarea",
"@value":"Default text"
}
}

== Proposal B: REST-oriented process ==
From [Kyle Cordes], for the discovery of the parameters:

* You discover the URL of a service by some means.
* You GET that URL, which returns an HTML form.
* The HTML form describes where to POST to invoke that service, and what
parameters can be passed in that POST. In some cases, it will use
<selects>s to describe what options are valid for a parameter.
* In most cases, the form will be interspersed with human readable text,
to explain the meaning of the parameters (a machine-understandable way
to explain parameter meaning, sounds like an AI problem...)
* You (the user of a web browser, or a piece of software
programmatically using the server) populate the parameters and POST them
to the URL you discovered via the form.
* You get back a response, which might be an error message about a
parameter problem, or might be a respresentation of the "answer".

== 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]]

rest/brainstorming

2006-10-09T14:13:58Z

OlaBerg: /* See Also */

= 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 three types of URIs:
;base:The base URI for the web service, e.g.: <code>http://example.com/site/</code>.
;records:URIs representing individual entities, e.g.: <code>http://example.com/webservice/users/me%40drernie.com</code>.
;tables:The URIs used to create or search for those instances, e.g.: <code>http://example.com/webservice/users</code>.

Note that each record is defined by a set of key-value pairs living under that table.

There can also be 'singletons' - a class which only has a single instance.

=== Verbs ===

REST depends on using verbs properly. Your typical verbs are POST (create), GET (retrieve), PUT (update), and DELETE (delete). More verbs can be defined and used, but the listed above are most commonly used and supported.

As we know, HTML forms spec (and therefore commonly used UAs) only provides support for POST and GET verbs. This limitation has been the biggest argument against mixing HTML and REST: tunnelling of PUT and DELETE verbs through POST (or even worse, GET) creates architectural unREST.

However, some architectures simply do not need deletion and update operations. Using HTML with REST requires employing such architectures.

While that may seem overly restrictive, as a practical matter those cover the "80%" of public web services we are trying to solve (after all, you are welcome to use your own private methods if you need to).

Even better, we can define very precise semantics for what GET & POST mean for each of the different nouns:

GET base
GET base?view=api # Return hyperlinks and forms
GET base?query # search for records across multiple table

GET table
GET table?view=api
GET table?query # search for records in that table
POST table?create # create record

GET record # encode as xoxo
GET record?view=edit # encode as hyperlinks/anchors
GET record?view=api # encode as hyperlinks/anchors + descriptions
POST record?update # update record -- this is tunnelling, a no-no

For simplicity, we assume:
* users can not delete anything
* users can not create tables (or singletons)

To be sure, there are natural ways to extend this protocol to provide that functionality. However, as that is primarly for admin usage, and thus a private API, we're glossing over it here. From a user's point of view, we provide analogous capabilities using POST:
* "DELETE" is replaced by "mark for deletion"
* "PUT" is replaced by "ask table to create record"

=== Format ===

Results should be returned in a xoxo-compatible format. In particular, query results should leverage
[http://opensearch.a9.com/spec/opensearchresponse/1.1/ OpenSearch 1.1].

[''Do HTML bindings for this already exist?'']

== Questions for further research ==

== Patterns ==

=== Anchor Design Pattern ===

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

=== Forms Design Pattern ===

I use a number of <form>s to declare the API for a web resource:

<div class="function">
The visual human name in h1-tags:

<h1>Foobalize</h1>

A human readable explanation using in some html.

<p>Foobalizer foobalizes grunts and glomph. Note that blorks already must be gazzed!
</p>

Then the form that specifies one function:

<form id="fooblize" action="GET" action="http://www.example.com/glurt">
<div class="field">
<label for="grunt">Grunt</label> <input type="text" class="varchar(20)" />
</div>
<div class="field">
<label for="grunt">Blork</label> <input type="text" class="int4" />
</div>
<input type="submit" value="Foobalize" />
</form>

</div>

== 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-proposal-preso]]
* [[duhper-proposal-preso]]

[http://www.opendarwin.org/~drernie/rest-api.html Proposed REST API]

rest/brainstorming

2006-10-09T14:11:49Z

OlaBerg: /* Forms Design Pattern */

= 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 three types of URIs:
;base:The base URI for the web service, e.g.: <code>http://example.com/site/</code>.
;records:URIs representing individual entities, e.g.: <code>http://example.com/webservice/users/me%40drernie.com</code>.
;tables:The URIs used to create or search for those instances, e.g.: <code>http://example.com/webservice/users</code>.

Note that each record is defined by a set of key-value pairs living under that table.

There can also be 'singletons' - a class which only has a single instance.

=== Verbs ===

REST depends on using verbs properly. Your typical verbs are POST (create), GET (retrieve), PUT (update), and DELETE (delete). More verbs can be defined and used, but the listed above are most commonly used and supported.

As we know, HTML forms spec (and therefore commonly used UAs) only provides support for POST and GET verbs. This limitation has been the biggest argument against mixing HTML and REST: tunnelling of PUT and DELETE verbs through POST (or even worse, GET) creates architectural unREST.

However, some architectures simply do not need deletion and update operations. Using HTML with REST requires employing such architectures.

While that may seem overly restrictive, as a practical matter those cover the "80%" of public web services we are trying to solve (after all, you are welcome to use your own private methods if you need to).

Even better, we can define very precise semantics for what GET & POST mean for each of the different nouns:

GET base
GET base?view=api # Return hyperlinks and forms
GET base?query # search for records across multiple table

GET table
GET table?view=api
GET table?query # search for records in that table
POST table?create # create record

GET record # encode as xoxo
GET record?view=edit # encode as hyperlinks/anchors
GET record?view=api # encode as hyperlinks/anchors + descriptions
POST record?update # update record -- this is tunnelling, a no-no

For simplicity, we assume:
* users can not delete anything
* users can not create tables (or singletons)

To be sure, there are natural ways to extend this protocol to provide that functionality. However, as that is primarly for admin usage, and thus a private API, we're glossing over it here. From a user's point of view, we provide analogous capabilities using POST:
* "DELETE" is replaced by "mark for deletion"
* "PUT" is replaced by "ask table to create record"

=== Format ===

Results should be returned in a xoxo-compatible format. In particular, query results should leverage
[http://opensearch.a9.com/spec/opensearchresponse/1.1/ OpenSearch 1.1].

[''Do HTML bindings for this already exist?'']

== Questions for further research ==

== Patterns ==

=== Anchor Design Pattern ===

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

=== Forms Design Pattern ===

I use a number of <form>s to declare the API for a web resource:

<div class="function">
<h1>Foobalize</h1>

<p>Foobalizer foobalizes grunts and glomph. Note that blorks already must be gazzed!
</p>

<form action="GET" action="http://www.example.com/glurt">
<div class="field">
<label for="grunt">Grunt</label> <input type="text" class="varchar(20)" />
</div>
<div class="field">
<label for="grunt">Blork</label> <input type="text" class="int4" />
</div>
<input type="submit" value="Foobalize" />
</form>

</div>

== 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-proposal-preso]]
* [[duhper-proposal-preso]]

[http://www.opendarwin.org/~drernie/rest-api.html Proposed REST API]