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


Ignore:
Timestamp:
03/03/14 20:38:53 (7 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/Tutorial/RESTCustomisation

    v14 v15  
    5656or:
    5757
    58 {{{
     58{{{#!python
    5959class AvailableShelters(S3Method):
    6060    """
     
    157157}}}
    158158
    159 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.
    160 
    161 But for any other record we intend to return to the user, we must check permissions explicitly in the method handler.
    162 
    163 Note that you must request permission for ''every'' table that you intend to return information about.
    164 
    165 === S3Method Subclasses as Method Handlers ===
    166 
    167 Method handlers can also be defined as subclass of S3Method:
    168 
    169 {{{
    170 class AvailableShelters(S3Method):
    171     """
    172         Method handler for the "available_shelters" method
    173     """
    174 
    175     def apply_method(self, r, **attr):
    176         """
    177             Entry point for the RESTful API
    178 
    179             @param r: the S3Request
    180             @param attr: additional keyword parameters passed from the controller
    181         """
    182 
    183         # do something to produce output
    184 
    185         return output
    186 
    187 }}}
     159Note 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 from which we return information to the user, or any other method we intend to perform, we must first check permissions in the method handler.
    188160
    189161=== Configuring a Method Handler ===
    190162
    191 To configure a method handler for a resource, use the {{{set_method()}}} function in S3Model (current.s3db):
     163Eventually, we need to tell the REST API which function/class to call for the ''available_shelters'' qualifier:
    192164
    193165{{{
     
    202174                                  *s3_metafields())
    203175
    204         # Configure a custom method (with S3Method subclass)
     176        # Configure a custom method
    205177        self.set_method("pr", "group", method="available_shelters", action=AvailableShelters)
    206178
    207179        ...
    208180
    209 class AvailableShelters(S3Method):
    210     """
    211         Method handler for the "available_shelters" method
    212     """
    213 
    214     def apply_method(self, r, **attr):
    215         """
    216             Entry point for the RESTful API
    217 
    218             @param r: the S3Request
    219             @param attr: additional keyword parameters passed from the controller
    220         """
    221 
    222         # do something to produce output
    223 
    224         return output
    225 
    226181}}}
    227182
    228 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:
     183This can be done both in the model (like above, so it is available in all controllers), or in just the controller that needs it.
    229184
    230 {{{
    231 def group():
    232     """ RESTful Controller for pr/group """
    233 
    234     # Configure the handler for pr/group/N/available_shelters
    235     s3db.set_method("pr", "group", method="available_shelters", action=available_shelters_handler)
    236 
    237     return s3_rest_controller()
    238 
    239 def available_shelters_handler(r, **attr):
    240     """
    241         Method handler for the "available_shelters" method
    242 
    243         @param r: the S3Request
    244         @param attr: additional keyword parameters passed from the controller
    245     """
    246 
    247     # do something to produce output
    248 
    249     return output
    250 
    251 }}}
     185Note that if the method handler is implemented as S3Method subclass, we do ''not'' need to instantiate it. It will be instantiated only when it is needed to process the request.