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

== Introduction ==

Resources are dynamic, document-alike representations of data objects on the Eden server. As such, they can represent both single instances as well as structured sets of data objects.

    ''Note: in the database context, a single instance of a data object is typically called a record (or row), with fields (or columns) as its atomic elements. However, even though S3Resources are typically bound to a relational database and therefore the record/field terminology is often used in this regard, they are '''''not''''' intended to provide any object-relational mapping (ORM).''

S3Resources implement an extensible, multi-format [http://en.wikipedia.org/wiki/REST REST]ful API to retrieve and manipulate data on the Eden server by [http://en.wikipedia.org/wiki/HTTP HTTP] requests, where every resource can be addressed by an individual [http://en.wikipedia.org/wiki/URL URL].

In the context of the Model-View-Controller (MVC) architecture, S3Resources are controller-generated objects. Typically, the controller generates a resource in response to an incoming HTTP request and returns a view of it (''output'') to the client:

    [[Image(arch3.png)]]


== Terminology ==

A S3Resource consists of elements which can be either ''resource''s themselves (container type) or ''data'' (atomic types).

Container type elements within a resource can be:

  - primary resources (independent data objects)
  - component resources (objects which are part of a primary object)
  - referenced resources (objects which are referenced by primary or component resources)

== RESTful API ==
=== Flow Diagram ===

[[Image(s3rest.png)]]


=== Description ===

The [http://eden.sahanafoundation.org/wiki/S3XRC/RESTfulAPI/s3_rest_controller s3_rest_controller] function is a helper function which easily apply the RESTful API over your controller.
Every time user request for a resource the s3_rest_controller function is called and return an output which then is passed to the view.
The above diagram explains how a s3_rest_controller responds to request and gives the generate the desired output.

* So first s3_rest_controller function parse the request object to S3Request class to generate S3Request object (r) having following attributes  [http://eden.sahanafoundation.org/wiki/S3XRC/RESTfulAPI/S3Request S3Request]
* During this process S3Resource or r.resource is also generated 

* Then different method handlers are configured using set_handler function.

* After that  S3Request is executed, During execution first thing that occur is a check for any hook to prep function, [http://eden.sahanafoundation.org/wiki/S3XRC/RESTfulAPI/s3_rest_controller#Pre-Process prep] is defined to get s3rest functionality, prep hook would allow you to change the handler configuration in certain situations.

* Then method handler is determined , i.e the GET,POST,PUT,DELETE or other custom method
* Then the handler are executed to get the desired output,If the no handlers are present , then the S3CRUD method is called which fills the output with create, update , list or delete form.

* And then a check for any hook to postprocessor occurs.

* Then some action buttons are added and the output is send to the view.

In case of interactive views output would be a dictionary with components that are then passed to the view, 
this could also contain a form.


----
DeveloperGuidelines