BluePrintREST – SahanaEden

Context Navigation

Version 27 (modified by Fran Boon, 16 years ago) ( diff )
Update for current status

RESTful API

This page hosts detailed specifications for Blueprint for the RESTful API.

NB This work is mostly done - 'just' need to add support for more representations:

JSON uploads via POST
- retrieve raw POST data using: request.body.read()
- send POST data using http://docs.jquery.com/Ajax/jQuery.post#urldatacallbacktype
  - jquery.ajax supports username/password: http://docs.jquery.com/Ajax/jQuery.ajax#options
  - Cross-domains using JSONP: http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/
RSS
- import gluon.contrib.rss2 as rss2 (see T3/controllers/default.py)
GeoRSS, KML, GPX, GML, WKT (BluePrintGISImportExport)
CSV, RTF (native to Web2Py)
PDF

Also can add extra methods to the controller, such as:

Search (make this the default if many records found?): t2.search()

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 used in a slightly RESTful way anyway (resources are URLs), 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 have changed to URLs like these (see BluePrintRESTImplementation):

/sahana/gis/feature           # Acts as 'list' (or list_add if t2.logged_in)
/sahana/gis/feature/id        # Acts as 'display'
/sahana/gis/feature/create
/sahana/gis/feature/display/id
/sahana/gis/feature/update/id
/sahana/gis/feature/delete/id

we could potentially do these:

/sahana/gis/feature/id?method=display
/sahana/gis/feature/id?method=update
/sahana/gis/feature/id?method=delete

but T3 requires ID to be the last argument, so can't do URLs like: /id/create

These are the benefits:

Consistency & ease of implementation of all basic functionality for new tables.

Simplified ability to create .represent widgets:

def shn_list_item(table,resource,action,display='table.name',extra=None):
    if extra:
        items=DIV(TR(TD(A(eval(display),_href=t2.action(resource,[action,table.id]))),TD(eval(extra))))
    else:
        items=DIV(A(eval(display),_href=t2.action(resource,[action,table.id])))
    return DIV(*items)

This is extended to export raw data in other formats, using the optional vars:

/sahana/gis/feature/display/id?format=[json|xml|csv]

which was considered better than using another arg:

/sahana/gis/feature/display/[json|xml|csv]/id

NB Web2Py currently doesn't support HTTP PUT/DELETE/UPDATE (only GET).
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: