Request API
From Project Auriga
While we are still making use of sessions, a large part of the API has moved to a REST model. This page describes the vocabulary.
Contents |
[edit] Controller
All new development is centered around public_html/dispatcher.php, which provides the following behavior by default. All code requests go through this stub, which is responsible for the view and module_id parameters.
[edit] Methods
Following REST conventions, we are using GET, POST, PUT, and DELETE to indicate particular types of actions:
- GET - should not result in any change of the system. Used to load information about the system, current state, and things along those lines.
- POST - Used to add new items to the system, or to modify particular attributes. This is widely used to start/stop timers, or for editing particular attributes.
- PUT - Mainly used to update entire objects. Sometimes it's used to add new ones.
- DELETE - not currently implemented, but will be used to delete objects.
In the PHP controllers, any data to be written to the database should be read from the POST array or the PUT body. The handle_put function in utils.php reads from the raw request, and can convert it to an array for PUT, or a SimpleXML document for either PUT or POST requests that pass an XML document instead of name=value pairs.
The key parameters listed below are read from $_REQUEST, so that form submissions may override GET addresses.
[edit] Key parameters
Dispatcher.php expects, and handles, the following parameters:
- module_id
- action
- view
- date
module_id is looked up in the global $modules array (created in site_registry.php) to find a controller class. This controller class is instantiated with the current user (created by session_login.php) and date objects (mainly a legacy). The controller object's get_view method is then called with the action, Smarty object, and view.
The action is completely defined by the individual controller class.
The view parameter indicates what the Ajax code expects in return, and makes a huge difference in how code is executed.
[edit] Views
There are four basic types of views:
- null (not specified) - load full template, with module as specified
- json, json-comment-filtered - skip loading Smarty, take object->get_view return value and convert to a JSON string.
- xml - skip loading Smarty, take object->get_view return value and serialize into XML string (handles either a SimpleXML or DOMDocument object).
- anything else - return whatever string is returned by object->get_view as a string. Usually a Smarty template for a particular module.
[edit] Other
The rest of the API is determined by individual controller classes.
