Developing Actions

Evan Tahler edited this page May 2, 2011 · 12 revisions

The meat of DAVE is how simple it is to develop custom actions for your API.

What is an Action?

An action is a linear logical sequence which preforms calculations or manipulates data. An Action is a simpler representation of a Controller + View from MVC parlance. Dave also creates linear actions which may deal directly with the data base (model).

A user requests that a certain action be preformed with the Action parameter. In this API, Actions are NOT restFUL, and are meant to be defined explicitly. For example, rather than having an ambiguous /User/ controller which may contain user creation, view, etc, DAVE should have very clear UserAdd, UserView, UserDelete, and UserEdit actions. You may, of course create an action called "User" with another parameter of "Mode" which might be the traditional REST verbs, but that is still nice and clear. The reason for this choice is to help clients who may not be able to have access to all the HTTP verbs (get, put, etc) to be able to interact with this API.

*The option to add restFUL URLs to you actions has been added. This assumes mod_rewrite or similar is installed on your web-srver which will direct all un-matched requests to index.php

A very simple action to return the user's posted name would be:

if ($ERROR == 100){
  if(isset($PARAMS['name'])){
    $OUTPUT["Your_Name"] = $PARAMS['name'];
  } else {
    $OUTPUT["Your_Name"] = "UNKNOWN";
    $ERROR = "You did not provide a name";
  }
}

Actions are where you might integrate with another API, another toolkit (perhaps the ZEND framework), etc. If there are common functions you might use over and over, like validating an email address, it's common practice to place those functions in CommonFunctions.php, or their own file within API/helper_functions/

Configuring your Action

Actions need to be defined in the $ACTIONS variable, and are defined in Actions.php. This ensures that only explicitly defined files will be executed by the API. $ACTIONS is an array with each entry being an array that contains the following:

array('ACTION_NAME', 'PATH_TO_ACTION.php', 'Public_or_Private', 'optional_rest_url');

An example would be:

$ACTIONS[] = array('DescribeActions', 'Actions/examples/DescribeActions.php', 'Public', "/DescribeActions");

Important Variables to use in your Actions

$ERROR

$ERROR is the global state variable for the duration of the entire request. '100' is the OK value, and any other value is considered to be an error. If the request gets to your Action, that means that the $ERROR is 100. The design pattern for Action is to procede linearly checking the Value of $ERROR at each step. For example, if you are creating an action to register a new user, you might first check to see if they provided a ScreenName and a password. If the password is missing you might set $ERROR to be "You need to provide a password". This message will be returned to the user as part of the $OUTPUT response. Your next logical block, perhaps writing the user to the DB would check to ensure that $ERROR == 100, and would not continue in this case.

$OUTPUT

$OUTPUT is an associative array (Hash) whose entire contents will be returned to the user at the end of handling the request. Do not use "echo" or "print" anywhere in the API, as this response may not get rendered properly. You can add depth (sub arrays) to $OUTPUT.

$PARAMS

$PARAMS is the collection of input the user provided to the API. $PARAMS is populated by first looking at $_GET, then $_POST, and finally $_COOKIE (in this order, which will overrite!). However, only variables which are defined in $POST_VARIABLES will be included. $POST_VARIABLES contains mySQL column names automatically. You can add to this list with custom variables you wish to accept from within GetPostVars.php.

$DBObj

$DBObj is the mySQL connection object. If you ever need to connect to mySQL directly with a complicated query, please use this connection and do not spawn a new one. You can use $DBObj->Query($SQL) and $DBObj->GetResults() to make raw requests. Many server environments can only allow one mySQL connection per request 'thread'. Check the documentation in "ConnectToDatabase.php" for details.