[[TOC]]
[wiki:S3XRC] | [wiki:S3XRC/RESTfulAPI S3 RESTful API] | s3_rest_controller
= s3_rest_controller =

== Introduction ==

The so-called '''REST Controller''' (function {{{s3_rest_controller()}}}) is a helper function to easily apply the RESTful API of the S3Resource class to your controller.

{{{s3_rest_controller}}} does:

  - parse and execute the incoming HTTP request on the specified resource
  - populate and hand-over view variables
  - choose and set the response view template ({{{response.view}}})

Using {{{s3_rest_controller}}}, a basic RESTful controller for the {{{pr_image}}} table can look like:

{{{
def image():

    """ RESTful CRUD controller """

    return s3_rest_controller("pr", "image")

}}}

This exposes all standard [wiki:S3XRC/RESTfulAPI/URLFormat URLs] and [wiki:S3XRC/RESTfulAPI methods] for this table, including:

  - interactive create, read, update, delete and list views
  - non-interactive data export/import (GET/POST/PUT/DELETE) in multiple formats

== Syntax ==

{{{
output = s3_rest_controller(prefix, resourcename)
}}}

  - '''prefix''' is the application prefix of the resource
  - '''resourcename''' is the name of the resource (without prefix)

  - '''output''' contains the result of the request and can be returned from the controller as-is
    - in interactive view formats, this is a {{{dict}}} of view variables

=== Additional View Variables ===

In interactive view formats, any additional named arguments in the {{{s3_rest_controller}}} argument list will be added to the view variables:

{{{
output = s3_rest_controller(prefix, resourcename, **attr)
}}}

  - '''**attr''': additional view variables


  - any callable argument will be invoked with the {{{S3Request}}} as first and only argument, and its return value will be added to the view variables
  - any non-callable argument will be added to the view variables as-is
  - any argument that gives {{{None}}} will remove this key from the view variables

A typical use-case is '''rheader''':

{{{
def my_rheader(r):
  if r.interactive and r.component:
    # Code producing the rheader...
    return rheader
  else:
    return None

output = s3_rest_controller(prefix, name, rheader=my_rheader)
}}}

If {{{my_rheader(r)}}} gives something else than {{{None}}}, then this value is added as {{{rheader}}} to the view variables.

----

DeveloperGuidelines