[[TOC]]
= S3REST and XRequest =

== s3rest ==

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

[[Image(s3rest.png)]]

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

== XRequest ==

=== Attributes of the XRequest ===

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

==== Controller Attributes ====

||'''rc'''||the resource controller object (''S3XRC'')||
||'''request'''||the original web2py request (''Storage'')||
||'''session'''||the current session (''Storage'')||

==== Request Attributes ====

||'''representation'''||the current representation of this request (''string'', lowercase)||
||'''http'''||the HTTP method of this request (''string'', always uppercase!)||
||'''extension'''||the extension found in the original request (''string'', lowercase)||
||'''method'''||the method of the request if not HTTP (''string'', always lowercase)||
||'''custom_action'''||the custom method handler for the request (''function'' or ''lambda'')||

==== Primary Resource Attributes ====

||'''prefix'''||the prefix (=module name) of the requested resource (''string'')||
||'''name'''||the name of the requested resource, without prefix (''string'')||
||'''tablename'''||the name of the primary table (''string'')||
||'''table'''||the primary table (''Table'')||
||'''id'''||the ID of the primary record (''int'')||
||'''record'''||the primary record (''Row'')||

==== Component Resource Attributes ====

||'''component'''||the requested component, if any (''!ObjectComponent'')||
||'''pkey'''||the primary key of the Resource/Component join (''string'')||
||'''fkey'''||the foreign key of the Resource/Component join (''string'')||
||'''component_name'''||the name of the component without prefix (''string'')||
||'''component_id'''||the ID of the component record as of the request, if any (''int'')||
||'''multiple'''||Flag indicating that multiple component records are allowed (''boolean'')||

==== Error Indicators ====

||'''error'''||the last error message (''string'')||
||'''invalid'''||Flag indicating this request as invalid (''boolean'')||
||'''badmethod'''||Flag indicating a bad method error (''boolean'')||
||'''badrecord'''||Flag indicating a invalid record ID error (''boolean'')||
||'''badrequest'''||Flag 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)'''
  - exporta 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)'''
  - export the options of a field in the resource as XML

'''options_json(pretty_print=False)'''
  - export the options of a field in the resource as JSON