wiki:S3REST

Version 11 (modified by Dominic König, 12 years ago) ( diff )

--

S3REST and XRequest

s3rest

s3rest is a callable global object which implements the RESTful interface for the S3 framework.

s3rest is an instance of the RESTController class, implemented in modules/s3rest.py.

s3rest uses the XRequest class (described below) to represent the current REST request, instead of the web2py request object. Other than web2py/request, the XRequest of the current call is not a global object, but passed as argument when calling REST method handlers.

Method Handlers

The default method handlers for each of CRUD+S are implemented in models/01_RESTlike_controller.py:

  • shn_read(jr, attr)
  • shn_list(jr, attr)
  • shn_create(jr, attr)
  • shn_update(jr, attr)
  • shn_delete(jr, attr)
  • shn_search(jr, attr)
  • shn_options(jr, attr)
  • import_xml(jr, attr)
  • import_json(jr, attr)

where jr is the current XRequest, and attr contains all further arguments passed to the REST controller.

You can override these defaults at any time by

s3rest.set_handler(action, handler)

where:

  • action is the name of the action, i.e. one of 'read', 'list', 'create', 'update', 'delete', 'search', 'options', 'import_xml' or 'import_json'
  • handler is the handler function/lambda

Custom Methods

You can also add resource-specific custom methods by:

  s3xrc.model.set_method(module, resource, method, action)

where:

  • module is the module prefix of a resource
  • resource is the name of the resource (without prefix)
  • method is a string representing the name of the method (e.g. "search_simple")
  • action is the method handler function/lambda

The action method has to take the same arguments as the default handlers: jr (XRequest) and attr.

XRequest

Attributes of the XRequest

The following attributes are set during initialisation of an XRequest object, no further call is required.

Controller Attributes

rcthe resource controller object (S3XRC)
requestthe original web2py request (Storage)
sessionthe current session (Storage)

Request Attributes

representationthe current representation of this request (string, lowercase)
httpthe HTTP method of this request (string, always uppercase!)
extensionthe extension found in the original request (string, lowercase)
methodthe method of the request if not HTTP (string, always lowercase)
custom_actionthe custom method handler for the request (function or lambda)

Primary Resource Attributes

prefixthe prefix (=module name) of the requested resource (string)
namethe name of the requested resource, without prefix (string)
tablenamethe name of the primary table (string)
tablethe primary table (Table)
idthe ID of the primary record (int)
recordthe primary record (Row)

Component Resource Attributes

componentthe requested component, if any (ObjectComponent)
pkeythe primary key of the Resource/Component join (string)
fkeythe foreign key of the Resource/Component join (string)
component_namethe name of the component without prefix (string)
component_idthe ID of the component record as of the request, if any (int)
multipleFlag indicating that multiple component records are allowed (boolean)

Error Indicators

errorthe last error message (string)
invalidFlag indicating this request as invalid (boolean)
badmethodFlag indicating a bad method error (boolean)
badrecordFlag indicating a invalid record ID error (boolean)
badrequestFlag indicating an unqualified request error (boolean)

ObjectComponent contains:

  • prefix, name, table_name, table and attr of the component
  • attr contains:
    • multiple Multiple-flag
    • editable, deletable and listadd
    • list_fields, rss, main and extra
    • onaccept, onvalidation, delete_onaccept and delete_onvalidation
  • methods: set_attr() and get_attr()

Methods of the XRequest

here(representation=None)

  • returns the URL of the current request

there(representation=None)

  • returns the URL of a HTTP GET request for the same resource

same(representation=None)

  • returns the URL of the current request with the primary record ID replaced by the string literal '[id]'

other(method=None, record_id=None, representation=None)

  • returns the URL of a request with another method and record ID, but for the same resource

target()

  • returns the target table of the current request as tuple of (prefix, name, table, tablename)

export_xml(permit=None, audit=None, template=None, filterby=None, pretty_print=False)

  • exports the requested resources as XML

export_json(permit=None, audit=None, template=None, filterby=None, pretty_print=False)

  • exports the requested resources as JSON

import_xml(tree, permit=None, audit=None, onvalidation=None, onaccept=None)

  • import the requested resources from the given ElementTree

options_xml(pretty_print=False)

  • exports the options of a field (or all fields) in the resource as XML

options_json(pretty_print=False)

  • exports the options of a field (or all fields) in the resource as JSON

Attachments (1)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.