[[TOC]]
= s3_rest_controller =

  - [wiki:S3XRC]
  - [wiki:S3XRC/RESTfulAPI S3 RESTful API]

== 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 additional view components
  - choose and set the response view template (response.view)

== Syntax ==

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

  - '''prefix''' is the application prefix of the resource
  - '''resourcename''' is the name of the resource (without prefix)
  - '''**attr''' are any additional view components

  - 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 variables for the view

=== Additional View Components ===

Additional named arguments in the s3_rest_controller call control the output dict ''after'' the request has been executed:

  - any callable argument will be invoked with the S3Request as first and only argument, and its return value will be added to the output dict instead
  - any non-callable argument which is not None is added to the output dict as-is
  - any argument that gives None will remove this key from the output dict

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)
}}}

In this case, the rheader variable is only added to the output when the my_rheader function returns something else than None.

----

DeveloperGuidelines