Changes between Version 13 and Version 14 of DeveloperGuidelines/Tutorial/RESTCustomisation

Timestamp:

03/03/14 20:33:43 (11 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelines/Tutorial/RESTCustomisation

@@ -1 +1 @@
 [[TOC]]
-= S3REST Customisation Mini Tutorials =
-
-see also: [wiki:RESTController RESTController], [wiki:S3REST S3REST]
-
-== S3REST and CRUD Method Handlers ==
-
-It seems generally difficult for new developers to understand how to take control of functionality in the [wiki:RESTController] of the S3 framework.
-
-IMHO that is because most of the examples look like that:
-{{{
-def myresource():
-
-   """ RESTful CRUD controller """
-
-   return shn_rest_controller(module, resource)
-}}}
-This in fact leaves it all to the shn_rest_controller function - hard to see what really happens.
-
-However, shn_rest_controller does not actually mean you would be tied to the CRUD method handlers of {{{01_crud.py}}}. REST merely cares for the proper resolution of URLs and HTTP methods, and then calls hooked-in functions to process the requests, and hooks can be manipulated.
-
-First of all - shn_rest_controller returns some output:
-{{{
-def myresource():
-
-   """ RESTful CRUD controller """
-
-   output = shn_rest_controller(module, resource)
-   return output
-}}}
-
-In case of interactive views, this output would be a dict with the components that are then passed to the view (by "return output" here). This could contain a form, for example:
-{{{
-def myresource():
-
-   """ RESTful CRUD controller """
-
-   output = shn_rest_controller(module, resource)
-   if isinstance(output, dict):
-       form = output.get("form", None)
-       if form:
-           # Your code to manipulate the form goes here:
-           ...
-
-   return output
-}}}
-
-That also means, you can add more items to the output dict:
-{{{
-def myresource():
-
-   """ RESTful CRUD controller """
-
-   output = shn_rest_controller(module, resource)
-   if isinstance(output, dict):
-       form = output.get("form", None)
-           if form:
-               # Code to manipulate form goes here:
-               ...
-       myitem = "I can send this item to the view"
-       output.update(myitem=myitem)
-
-   return output
-}}}
-
-Secondly, the shn_rest_controller has multiple hooks, among others for CRUD method handlers. Look at how shn_rest_controller is actually defined:
-{{{
-def shn_rest_controller(module, resource, **attr):
-
-   s3rest.set_handler("import_xml", import_xml)
-   s3rest.set_handler("import_json", import_json)
-   s3rest.set_handler("list", shn_list)
-   s3rest.set_handler("read", shn_read)
-   s3rest.set_handler("create", shn_create)
-   s3rest.set_handler("update", shn_update)
-   s3rest.set_handler("delete", shn_delete)
-   s3rest.set_handler("search", shn_search)
-   s3rest.set_handler("options", shn_options)
-
-   output = s3rest(session, request, response, module, resource, **attr)
-   return output
-}}}
-
-This is nothing else than a wrapper for the global s3rest object (an instance of S3RESTController), which configures the CRUD handlers of {{{01_crud.py}}} as handlers for CRUD methods. You don't have to use shn_rest_controller to have a RESTful API, you can make your own handler configuration and call s3rest directly.
-
-But even when using shn_rest_controller, you can take control over what actually happens. A very comfortable (and recommended) way to get control over s3rest when using shn_rest_controller is to hook in prep and postp functions. Look at [wiki:S3REST] to find out when prep and postp hooks are invoked.
-
-A prep hook would allow you to change a handler configuration in certain situations, e.g. testing a URL variable:
-{{{
-def myresource():
-
-   """ RESTful CRUD controller """
-
-   # Define pre-processor as local function:
-   def _prep(jr):
-       mylist = jr.request.vars.get("mylist")
-       if mylist:
-           s3rest.set_handler("list", my_list_controller)
-       return True # do not forget to return True!
-
-   # Hook pre-processor into REST controller:
-   response.s3.prep = _prep
-
-   output = shn_rest_controller(module, resource)
-   return output
-}}}
-This example would switch to my_list_controller instead of shn_list in case there is a ?mylist= in the URL. In all other cases, the default handlers are executed as usual, you still have a RESTful API for your resources.
-
-While you can define prep's and postp's as local functions (as in the example above) or even lambdas, it is also very well possible to create more generic, reusable prep and postp functions (e.g. to implement different method handler configurations, or to catch certain situations to bypass the CRUD handlers, or to manipulate the output dict in a certain way).
-
-A very important structure during prep and postp is the S3RESTRequest object (usually instantiated as "jr"). This object contains all necessary
-information to process the current REST request, and it is passed to both prep and postp. See [wiki:S3REST#S3RESTRequest] for a list of attributes and methods.
-
-== Custom methods ==
-
-Let me give you another recipe:
-
-Imagine you have a resource "warehouse" and want to implement a function "report" that generates a report about the current status of the warehouse.
-
-Now you're gonna provide this report in a RESTful way, i.e. you want to provide it as a resource that can be addressed via URLs like:
-
-  - '''!http://site.myserver.org/eden/wm/warehouse/report'''
-
-
-and is provided in several different data formats beyond HTML (the interactive view), let's say - XLS and XML:
-
-  - '''!http://site.myserver.org/eden/wm/warehouse/report.xls'''
-  - '''!http://site.myserver.org/eden/wm/warehouse/report.xml'''
-
-How to tackle this? Yes - you can use shn_rest_controller for this!
-
-This could be your "warehouse" CRUD controller:
-
-{{{
-def warehouse():
-
-   """ RESTful CRUD controller """
-
-   return shn_rest_controller(module, resource, ...)
-}}}
-
-At first you implement your report function (in the controller file). This function takes the argument jr (=S3RESTRequest) and a dict of named arguments (just the same named arguments from the shn_rest_controller call above). This function returns the report. Then, in your controller, you plug in this function to your resource - together it would look like that:
-
-{{{
-def warehouse():
-
-    """ RESTful CRUD+Reports controller """
-
-    # Plug warehouse_report into warehouse resource:
-    s3xrc.model.set_method(module, resource, method="report", action=warehouse_report)
-
-    return shn_rest_controller(module, resource, ...)
-
-def warehouse_report(jr, **attr):
-
-    """ Warehouse report generator """
-
-    # Code to produce the report goes here
-    report = ...
-
-    return report
-}}}
-
-How to implement the report function now? Well - that's entirely up to you. In case of interactive views, you would usually return a dict of values that 
-are then formatted as HTML in the view template:
-
-{{{
-def warehouse_report(jr, **attr):
-
-    """ Warehouse report generator """
-
-    # Code to produce the report items:
-    title = T("Warehouse Report")
-
-    # Assemble the report items in a dict:
-    report = dict(title=title, ...)
-    return report
-}}}
-
-Note that if "report" is a dict, then the REST controller automatically adds the S3RESTRequest as "jr" to that dict before returning it. Thus, "jr" is 
-available to the view templates. That also means: do not use "jr" as key in that dict.
-
-However, there may be other formats than HTML - to implement other formats, you might need to check for the representation of the request. This can be 
-found in jr:
-
-{{{
-def warehouse_report(jr, **attr):
-
-    """ Warehouse report generator """
-
-    if jr.representation in ("html", "popup"):
-        # Code to produce the report items:
-        title = T("Warehouse Report")
-
-        # Assemble the report items in a dict:
-        report = dict(title=title, ...)
-
-    elif jr.representation == "xls":
-        # Code to produce the XLS report goes here
+= S3REST Customization =
+
+It is possible to extend the S3 RESTful API with custom methods.
+
+== An Example ==
+
+We want a RESTful method to return a list of available shelters that fit for a certain group of people.
+
+This is the '''URL''' to request the list of available shelters for a group:
+
+  * GET eden/pr/group/5/'''available_shelters'''
+
+This tutorial introduces the framework to implement such a method.
+
+== What is a Method Handler? ==
+
+When a REST request arrives at the API, it is dispatched to a function that executes the requested HTTP method for the record(s) addressed by the URL.
+
+In our example:
+
+  * GET eden/pr/group/5
+
+...the object is the '''pr_group''' record number '''5''' - and the requested method is HTTP '''GET'''. 
+
+The HTTP GET method, without any other arguments in the URL, would simply return the requested record.
+
+We can specify additional ''arguments'' for the GET function to tell the API exactly what kind of information about this record we would like to get:
+
+  * GET eden/pr/group/5/'''available_shelters'''
+
+Now the GET API function will try to find a '''method handler''', i.e. a function or class to deliver the ''available_shelters'' information for ''pr_group'' number ''5''.
+
+There is a number of ''standard'' method handlers available globally for all types of records, e.g. for CRUD (create, read, update, delete) or to generate certain types of reports (report, profile).
+
+Besides those standard methods, we can implement our own ''custom'' method handler for a particular table.
+
+== Implementing a Method Handler ==
+
+Such a '''method handler''' can be either a function or a class:
+
+{{{#!python
+def available_shelters_handler(r, **attr):
+    """
+        Method handler for the "available_shelters" method
+
+        @param r: the S3Request
+        @param attr: additional keyword parameters passed from the controller
+    """
+
+    # do something to produce output
+
+    return output
+}}}
+
+or:
+
+{{{
+class AvailableShelters(S3Method):
+    """
+        Method handler for the "available_shelters" method
+    """
+
+    def apply_method(self, r, **attr):
+        """
+            Entry point for the RESTful API (=this function will be called to handle the request)
+
+            @param r: the S3Request
+            @param attr: additional keyword parameters passed from the controller
+        """
+
+        # do something to produce output
+
+        return output
+
+}}}
+
+  Note: ''It is recommended to use the S3Method pattern because the S3Method class automatically takes care of certain additional controller parameters (in **attr, e.g. the "rheader") - whereas in a function we would have to implement those ourselves.''
+
+The output from the method handler (that is, the list of available shelters in our example) is then handed over to the view renderer, and from there returned to the client.
+
+== Where is the Request Information? ==
+
+Of course, the same method handler could also handle other types of request, e.g. when the user subsequently selects one of the shelters in the list in order to allocate it to the group number 5, then this would become:
+
+  * POST eden/pr/group/5/available_shelters
+
+Now it is the POST function calling our method handler, and to find out whether this is GET or POST, we can ''introspect'' the request object:
+
+{{{#!python
+class AvailableShelters(S3Method):
+
+    def apply_method(self, r, **attr):
+
+        if r.http == "GET":
+            # produce the list of available shelters
+
+            ...
+
+            # The requested record (pr_group 5) can be accessed like this:
+            # (note: r.record could be None if the record is not accessible or doesn't exist)
+            record = r.record 
+
+            # Similar, the ID of the requested record can be found in:
+            record_id = r.id
+
+            ...
+
+            return list_of_available_shelters
+
+        elif r.http == "POST":
+            # process the allocation of a shelter to this group
+
+            ...
+
+            # After the process, we would typically redirect to the next step
+            # in the workflow, or return to the same view in case of failure.
+            # In either case, we would show a message.
+            # In S3Method subclasses we use self.next to specify the redirection
+            # destination:
+
+            if allocation_success:
+                current.response.confirmation = T("Shelter allocated")
+                self.next = r.url(method="") # <= redirect e.g. to the pr_group view
+            else:
+                # Allocation has failed - return to the GET view?
+                current.response.error = T("Allocation failed")
+                self.next = r.url() # <= redirect to the same URL, but with HTTP GET
+
+            return # <= irrelevant what we return here, since we redirect anyway
+}}}
+
+== How to Authorize a Method ==
+
+When we implement a method handler that returns information, we need to request permission to do so:
+
+{{{#!python
+    if current.auth.s3_has_permission("read", "cr_shelter"):
+        # User is permitted to read in the shelter table
+
+        # Use this pattern to get a query that extracts only those records the user has permission to read:
+        table = current.s3db.cr_shelter
+        accessible_query = current.auth.accessible_query("read", "cr_shelter")
+
+        # This will return only the "accessible" rows
+        rows = current.db(accessible_query).select(table.id,
+                                                   table.name)
+
+        # NB: if we intend to subsequently allow the user to allocate shelter capacity, we may also want to
+        #     check whether the user is actually permitted both to read *and* to update the shelter information:
+        accessible_query = current.auth.accessible_query(["read", "update"], "cr_shelter")
+
+
+    else:
+        # Easy to tell that they are not permitted to read in the shelter table:
+        r.unauthorized()
+}}}
+
+Note that "read" permission for the requested record (pr_group 5) is already checked ''before'' the method handler is called, so it does not need to be checked again. 
+
+But for any other record we intend to return to the user, we must check permissions explicitly in the method handler.
+
+Note that you must request permission for ''every'' table that you intend to return information about.
+
+=== S3Method Subclasses as Method Handlers ===
+
+Method handlers can also be defined as subclass of S3Method:
+
+{{{
+class AvailableShelters(S3Method):
+    """
+        Method handler for the "available_shelters" method
+    """
+
+    def apply_method(self, r, **attr):
+        """
+            Entry point for the RESTful API
+
+            @param r: the S3Request
+            @param attr: additional keyword parameters passed from the controller
+        """
+
+        # do something to produce output
+
+        return output
+
+}}}
+
+=== Configuring a Method Handler ===
+
+To configure a method handler for a resource, use the {{{set_method()}}} function in S3Model (current.s3db):
+
+{{{
+class S3GroupModel(S3Model):
+    """ Model class for pr/group """
+
+    def model(self):
+
+        tablename = "pr_group"
+        table = self.define_table(tablename,
+                                  ...
+                                  *s3_metafields())
+
+        # Configure a custom method (with S3Method subclass)
+        self.set_method("pr", "group", method="available_shelters", action=AvailableShelters)
+
         ...
 
-    elif jr.representation in shn_xml_export_formats:
-        # Code to produce the XML report goes here
-        ...
-
-    else:
-        session.error = BADFORMAT
-        redirect(URL(r=jr.request))
-
-    return report
-}}}
-
-See [wiki:S3REST#S3RESTRequest S3RESTRequest] to find out more about "jr".
-
-To produce the XML report, it is probably sufficient to just export the requested warehouse information in S3XRC-XML, and then use XSLT stylesheets to produce the finally desired XML formats. That's pretty easy:
-
-{{{
-def warehouse_report(jr, **attr):
-    ...
-    elif jr.representation in shn_xml_export_formats:
-        report = export_xml(xrequest)
-    ...
-}}}
-
-Perhaps you want to add an RSS feed:
-
-{{{
-def warehouse_report(jr, **attr):
-    ...
-    elif jr.representation == "rss":
-        # Code to produce the RSS report goes here
-        report = ...
-    ...
-}}}
-
-Ah - now I forgot to mention how you can get at the data in the warehouse_report example.
-
-Your implementation already supports a variety of URLs:
-
-This URL addresses the report for all warehouses:
-  - '''!http://site.myserver.org/eden/wm/warehouse/report'''
-
-This URL addresses the report for the warehouse record with ID=1.
-  - '''!http://site.myserver.org/eden/wm/warehouse/1/report'''
-
-This URL addresses the report in XLS format for the warehouse record with the UUID=123654278 (assuming that you have UUID's in your warehouse table).
-  - '''!http://site.myserver.org/eden/wm/warehouse/report.xls?warehouse.uid=123654278'''
-
-The S3RESTRequest provides the resource information to your warehouse_report function.
-
-In case a specific record has been requested, you can access it as:
-{{{
-    record = jr.record
-}}}
-If jr.record is None, then the request is targeting all warehouse records, so you'd take:
-{{{
-    table = jr.table
-    records = db().select(table.ALL)
-    for record in records:
-       ...
-}}}
-instead.
-
-NOTE: representation in jr is always all lowercase, there is no differentiation between the ".XML" and ".xml" extension in the URL.
-
-And...not to forget: your warehouse_report is still a controller function, that means you can implement forms as usual (e.g. operated with form.accepts or web2py Crud).
+class AvailableShelters(S3Method):
+    """
+        Method handler for the "available_shelters" method
+    """
+
+    def apply_method(self, r, **attr):
+        """
+            Entry point for the RESTful API
+
+            @param r: the S3Request
+            @param attr: additional keyword parameters passed from the controller
+        """
+
+        # do something to produce output
+
+        return output
+
+}}}
+
+This can be done both in the model (like above, so it is available in all controllers), or in just the controller that needs it:
+
+{{{
+def group():
+    """ RESTful Controller for pr/group """
+
+    # Configure the handler for pr/group/N/available_shelters
+    s3db.set_method("pr", "group", method="available_shelters", action=available_shelters_handler)
+
+    return s3_rest_controller()
+
+def available_shelters_handler(r, **attr):
+    """
+        Method handler for the "available_shelters" method
+
+        @param r: the S3Request
+        @param attr: additional keyword parameters passed from the controller
+    """
+
+    # do something to produce output
+
+    return output
+
+}}}