= Google Code =

Most of this work has moved to [http://code.google.com/p/simcat SimCat], a Google Code project.

= Web Service =

Design notes on the CADAC web service.

== Protocols and Standards to Build On ==

=== Definitely ===

  * [http://www.opensearch.org/ OpenSearch]
  * [http://openid.net/ OpenId]
  * [http://www.xml.com/lpt/a/2004/12/01/restful-web.html REST]  

=== Maybe ===

  * [http://wikipedia.org/wiki/Atom_(standard) Atom Publishing Protocol]

== Resources ==

 {{{{member}}}}::
   A CADAC member.
 {{{{run}}}}::
   Job on a computer, batch or interactive, simulation or analysis.
 {{{{tag}}}}::
   Classic short tag, used to organize runs.
 {{{{computer}}}}::
   Machine used to do the work.
 {{{{program}}}}::
   Software doing the work.
 {{{{dataset}}}}::
   Output of the run.

== URIs and Operations ==

=== Canonical URIs - {{{GET}}} Returns XML ===

|| '''URI relative to [http://cadac.sdsc.edu]''' || '''{{{GET}}}''' || '''{{{PUT}}}''' || '''{{{POST}}}''' || '''{{{DELETE}}}''' ||
|| {{{/xml/members}}} || list of {{{{member}}}}s ||  || || ||
|| {{{/xml/members/{member}}}} || {{{{member}}}} information || add {{{{member}}}} || modify {{{{member}}}} || remove {{{{member}}}} ||
|| {{{/xml/members/{member}/runs}}} || list of {{{{member}}}}'s runs ||  ||  ||  ||
|| {{{/xml/members/{member}/runs/{run}}}} || {{{{run}}}} information || add {{{{run}}}} || modify {{{{run}}}} || remove {{{{run}}}} ||
|| {{{/xml/members/{member}/runs/{run}/tags}}} || list of {{{{run}}}}'s {{{{tag}}}s ||  ||  ||  ||
|| {{{/xml/members/{member}/runs/{run}/tags/{tag}}}} ||  || add {{{{tag}}}} || modify {{{{tag}}}} || remove {{{{tag}}}} ||

=== XHTML Rendered - {{{GET}}} Returns XHTML  === 

|| '''URI relative to [http://cadac.sdsc.edu]''' || '''{{{GET}}}''' || 
|| {{{/members}}} || list of {{{{member}}}}s || 
|| {{{/members/{member}}}} || {{{{member}}}} information ||
|| {{{/members/{member}/runs}}} || list of {{{{member}}}}'s runs ||
|| {{{/members/{member}/runs/{run}}}} || {{{{run}}}} information ||
|| {{{/members/{member}/runs/{run}/tags}}} || list of {{{{run}}}}'s {{{{tag}}}s ||

=== Convenience & Querying URIs ===

|| '''URI relative to [http://cadac.sdsc.edu]''' || '''{{{GET}}}''' || 
|| {{{/members/{member}/tags}}} ||  list of {{{{member}}}}'s {{{{tag}}}}s ||
|| {{{/members/{member}/runs/tag/{tag}}}} ||  list of {{{{member}}}'s {{{{run}}}}s with {{{{tag}}}} ||
|| {{{/members/{member}/runs/rss}}} ||  rss or atom feed of {{{{member}}}}'s {{{{run}}}}s ||
|| {{{/members/{member}/runs/{run}/rss}}} ||  rss or atom feed of {{{{run}}}} ||
|| {{{/members/{member}/runs/{tag}/rss}}} ||  rss or atom feed of {{{{run}}}}s with {{{{tag}}}} ||


== Representation ==

Need a means to distinguish between XHTML and XML representations. Perhaps the default with {{{GET}}} will be XHTML, to support browsers, and XML for the {{{PUT}}} and {{{POST}}} operations. XML could be specified for {{{GET}}} using {{{?fmt=xml}}}, or something similar. And the Atom or RSS feeds will be in their appropriate format.

== Permissions == 

For, now, assume all {{{GET}}}s are world readable, and all other operations require authentication by {{{{member}}}}.

== Implementation 0.1 ==

Use Apache mod_rewrite and !ProxyPass to map between the web server and the XML database. Use XSL to generate XHTML from native XML formats. Having the XML formats represented under something like {{{/xml/members}}}, allows {{{/members/{member}}}} to be rewritten to {{{/xml/members/{member}?_xsl=/stylesheets/member.xsl}}}. That way, eXist would build the XHTML. Likewise, RSS/Atom feeds will be generated using {{{/{foo}/rss}}} mapping to {{{/xml/{foo}?_xsl=/stylesheets/rss.xsl}}}.

Still need to deal with collection listings and {{{{run}/tags}}}, which is not a collection.

== Implementation 0.2 ==

I don't think I can build all of this using just rewrite rule. In particular, because we shouldn't make the client store all of the logic to deal with the database. The serving up the XHTML using a style sheet is simple and direct, but not handling {{{POST}}}s and {{{PUT}}}s that update the database.


Components
 * [http://foss.cpcc.edu/pyfo/ pyfo] ("Easily generate XML from Python data structures." True by all accounts.)
 * [http://lukearno.com/projects/selector/ selector] (Maps URI's to functions.)
 * [http://lukearno.com/projects/resolver/ resolver] ({{{selector}}} dependency.)

[http://lukearno.com/projects/selector/ selector] example using the standard module [http://docs.python.org/lib/module-wsgiref.html wsgiref]

{{{
def say_hello(environ, start_response):
   start_response("200 OK", [('Content-type', 'text/plain')])
   return ["Hello %s!" %environ['selector.vars']['name']]

from selector import Selector
s = Selector()
s.add('/myapp/hello/{name}', GET=say_hello)
from wsgiref.simple_server import make_server
httpd = make_server('', 8000,s)
httpd.serve_forever()
}}}

[http://foss.cpcc.edu/pyfo/ pyfo] example:

{{{
import pyfo
doc = ('Run',('Computer','Cobalt',{'ivo-id':'http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/SGIAltix/'}))
n = pyfo.pyfo(doc, pretty=True, prolog=True,encoding='utf8')
print n
<?xml version="1.0" encoding="utf8"?>
<Run>
  <Computer ivo-id="http://www.ncsa.uiuc.edu/UserInfo/Resources/Hardware/SGIAltix/">Cobalt</Computer>
</Run>
}}}


== Notes, Link ==

 * [http://www.xml.com/pub/a/2004/12/01/restful-web.html How to Create a REST Protocol] (i.e., How to design a RESTful API.)
 * [http://www.python.org/dev/peps/pep-0333/ PEP 333 Python Web Server Gateway Interface v1.0]
 * [http://www.xml.com/pub/a/2006/07/19/implementing-atom-publishing-protocol-python-wsgi.html Implementing the Atom Publishing Protocol] (i.e., Build a RESTful service using selector and wsgiref.)
 * [http://bitworking.org/news/Why_so_many_Python_web_frameworks Why so many Python web frameworks?] (i.e., How to Build a Web Service in 60 Lines.)