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] Store
(New) - The /store path is used by the Dojo JsonRestStore client data system. It supports a completely REST-ful API, with GET, PUT, POST, and DELETE for actions directly on data. The path of the store dictates what controller to load.
[edit] Store controllers
- /store/today - time_clock.class.php, returns time entries
- /store/project - project_c.class.php, returns projects. Children are top-level tasks.
- /store/task - task_c.class.php, returns tasks
- /store/account - account_c.class.php, returns accounts. Children are projects.
- /store/menu - menu_c.class.php returns menu items
- /store/project_type - project_c.class.php, returns project types
- /store/timeentry - task_c.class.php - returns time entries
- /store/tasklist - task_c.class.php - returns a tree structure with arbitrary lists. Children can be projects, time entries, tasks.
- /store/timer - time_timer.class.php - returns the active timers for users, and used to post timeclock changes
- /store/event - workpane.class.php - returns auriga events since the passed event id
- /store/workpane - ?
- /store/notice - notice_c.class.php - returns/sets active notices for a user
- /store/user_calendar - workpane.class.php - returns user calendar availability
- /store/user - workpane.class.php - returns users
- /store/report - report_c.class.php - returns reports
[edit] Store headers, parameters
Each store controller can accept arbitrary parameters, and specific resources under the main URL. Here are some conventions we use:
?view= [json, json-debug, xml, xmlstore, csv, csvt, html, body] - request specific response object to format return. If no view parameter is supplied, it checks the content-type in the request--JsonRestStore specified application/json. Default is XML.
HTTP_RANGE header: set to "items=0-49" to get first 50 results. Most controllers also support start= and count= GET parameters.
[edit] /store/tasklist
This is a tree store, with children items populated on a nightly basis and adjustable by users.
- /store/tasklist/today - list of time entries for today
- /store/tasklist/favorites - list of favorite projects/tasks
- /store/tasklist/week - list of time entries scheduled for next week
- /store/tasklist/search - empty, placeholder for populating client-side searches
- /store/tasklist/list - list of tasks the user wants to highlight ("doing now" list)
- /store/tasklist/later - list of tasks the user wants to defer ("doing later" list)
- /store/tasklist/new - list of tasks the user hasn't scheduled, or moved to list or later
[edit] Store items
The following define the structure of different store items, for reference when developing widgets.
[edit] Today Item (time entry)
Today items represent a specific time entry, with either a budgeted or actual time. This is the core unit for time tracking. All time entries must be associated with a task.
- Path: /store/today/xxxx
- Fields:
- task_id
- actual_time
- budget_time
- treetype = "timeentry"
- active - null or true - true if timer is running for this task
- Additional Optional Fields from task
- name
- task
- project
- account
- complete
- expected
- actual
- type
[edit] Task Item
Task items are tightly correlated with time entries, and must also be associated with a project.
- Path: /store/task/xxxx
- Fields:
- project_id
- name
- task
- expected
- actual
- complete
- treetype = "task"
- type
[edit] Project Item
Project items must be associated with an account.
- Path: /store/project/xxxx
- Fields:
- account_fk
- name
- project
- budget
- treetype = "project"
[edit] Other
The rest of the API is determined by individual controller classes.
