== RESTful API ==

This page hosts detailed specifications for [https://blueprints.launchpad.net/sahana3/+spec/rest Blueprint for the RESTful API].

Basic approach for the S3 architecture is to have a Web Services backend & a Javascript client front end.
RESTful APIs make this easier.

Web2Py generates URLs in this format:
{{{
/application/controller/function/arg1/arg2?var1=x,var2=y
}}}
These are generally fairly RESTful anyway, e.g.:
{{{
/sahana/gis/add_feature
/sahana/gis/list_features
/sahana/gis/features          # List_add
/sahana/gis/display_feature/1
/sahana/gis/update_feature/1
}}}
We can easily change to URLs like these (see [wiki:BluePrintRESTImplementation BluePrintRESTImplementation]):
{{{
/sahana/gis/feature           # Acts as 'list'
/sahana/gis/feature/id        # Acts as 'display'
/sahana/gis/feature/create
/sahana/gis/feature/list
/sahana/gis/feature/list_add
/sahana/gis/feature/display/id
/sahana/gis/feature/update/id
/sahana/gis/feature/delete/id
}}}
However, is there much benefit in this?[[BR]]
There are downsides:
 * We need to be authenticated for all actions (unless we patch T2)
 * Controller functions are less readable, with more levels of indent.
NB T3 requires ID to be the last argument, so don't want URLs like: /id/create

We want to be able extending this for exporting raw data in other formats, e.g. using the optional vars:
{{{
/sahana/gis/feature/display/x?format=[json|xml|csv]
}}}

Web2Py already supports export as JSON, CSV & RTF.
 * New SQLROW to JSON function: http://groups.google.com/group/web2py/browse_thread/thread/dfb65087574c24f1
 * For XML Parser discussions, look at [wiki:BluePrintGISImportExport BluePrintGISImportExport]

It would be best for us to add support to the framework to make it easy for module writers to have this functionality within their controllers.

NB Web2Py currently doesn't support HTTP PUT/DELETE/UPDATE (only GET).[[BR]]
This means a little work in clients but isn't too bad if we maintain consistency: no variations between add/create, view/display, edit/update, etc

Discussion of changes to Web2Py to make it more RESTful:
 * http://groups.google.com/group/web2py/browse_thread/thread/8506105246e319f6/
 * http://groups.google.com/group/web2py/browse_thread/thread/d9f7919c16d62514/
 * http://www.wellbehavedsystems.co.uk/web2py/examples/rest.html
 * http://www.wellbehavedsystems.co.uk/web2py/examples/rest_alt1.html
 * http://groups.google.com/group/web2py/browse_thread/thread/b46ff6f35e82f047
 * http://groups.google.com/group/web2py/browse_thread/thread/613d4ac6f87ad413/

=== Web Services ===
Allows multiple client UIs
 * http://talks.php.net/show/webservices/
 * http://webservices.xml.com/pub/a/ws/2004/03/24/phpws.html
 * http://wiki.sahana.lk/doku.php?id=dev:web_services

=== REST instead of SOAP ===
Less bloat, more GIS-friendly.
 * http://en.wikipedia.org/wiki/Representational_State_Transfer
 * Second Generation Web Services: http://www.onlamp.com/pub/a/php/2003/10/30/amazon_rest.html
 * Implementing REST Web Services: Best Practices and Guidelines: http://www.xml.com/pub/a/2004/08/11/rest.html
 * Common REST Mistakes: http://www.prescod.net/rest/mistakes/
 * How to Create a REST Protocol: http://www.xml.com/pub/a/2004/12/01/restful-web.html

=== Python REST Servers ===
 * http://mail.python.org/pipermail/python-list/2003-September/223257.html
 * http://www.rexx.com/~dkuhlman/rest_howto.html
 * FeatureServer: http://featureserver.org/
 * WebProcessingServer: http://code.google.com/p/webprocessingserver/
 * Tarawa framework: http://www.mnot.net/tarawa/tutorial.html
 * Rest in Python framework: http://lukearno.com/projects/rip/

=== Python REST Clients ===
 * Python client using urllib2: http://mail.python.org/pipermail/baypiggies/2008-January/002853.html
 * REST client lib: http://code.google.com/p/py-restlib/
 * GAE: http://code.google.com/p/python-rest-client/
 * wxWidgets desktop app: http://restclient.org/
 * REST framework for Zope: http://pypi.python.org/pypi/z3c.rest

=== Javascript REST clients ===
 * Ext JSONStore
 * http://giantrobots.thoughtbot.com/2007/6/11/jester-1-3-jsonic-rest
 * http://www.8wireunlimited.com/norockets/2008/10/jquery-vs-xslt-as-rest-client-for-xml-resource-in-the-browser/
 * http://www.nabble.com/-OT--Client-side-web-application-with-jQuery-td21043713s27240.html
 * Offline: http://www.dotnetkicks.com/opensource/SonicCast_7_SubSonic_REST_and_Jquery_AJAX

=== Other REST clients ===
 * http://www.postgresonline.com/journal/index.php?/archives/49-REST-in-PostgreSQL-Part-3-A-Simple-REST-Client-in-Adobe-Flex-3.html