Skip to content

Connecting to the API

evantahler edited this page · 11 revisions

All the contents of the $OUTPUT Array will be returned to the user and transformed bu Output.php into many possible formats for consumption.

Output Types

The default method of the API is set in CONFIG with the $CONFIG['DefaultOutputType'] variable., however clients can always request data in any of these types by providing the OutputType variable along with their request (GET, POST, or COOKIE). The DAVE API provide data responses in the following formats:

  • JSON
  • PHP Serialized
  • XML (simple)
  • PHP's var_dump output
  • LINE (and CONSOLE)

Connecting via PHP

If you are consuming this API from another PHP application, APIRequest class (API/AccessTools/APIRequest.php) is the way to go!. This class makes use of CURL and will make connecting to the API simple. False will be returned from DoRequest() upon error, and the $OUTPUT array from the API will be returned upon success.

$PostArray = array( 
    "Action" => "A_DUMMY_ACTION", 
    "OutputType" => "PHP"
);

$API_URL = "127.0.0.1/API/";
$APIRequest = new APIRequest($API_URL, $PostArray, $IP);
$APIDATA = $APIRequest->DoRequest();
if ($APIDATA != false)
{
    echo "Your request came from ".$APIDATA['IP']." and took ".$APIDATA['ComputationTime']." seconds.";
}
else
{
    echo 'Something is wrong with your URL or DAVE API configuration';
}

Notes on JSON

  • A Callback can be provided to JSON requests that will wrap the JSON response within a javascript function call. This is useful if you wish a callback function to be executed when the response is received. Use the Callback paramater for this. Be sure that this function is already defined on your page before the API request is made. Example:
<script>

var API_URL = "http://127.0.0.1:3000/";

function MakeJSONCallback(URL)
{
    URL = URL.toString();
    var script = document.createElement('script');
    script.src = URL;
    document.body.appendChild(script);
}

function api_request(Action, Callback, Params)
{
    t = new Date();
    timestamp = t.getTime();
    param_string = "?";
    param_string += "OutputType=JSON";
    param_string += "&RAND=" + timestamp;
    param_string += "&Action=" + Action;
    if(Callback == null){ Callback = "console.log"; }
    param_string += "&Callback=" + Callback
    for(x in Params)
    {
    param_string += "&" + encodeURIComponent(x) + "=" + encodeURIComponent(Params[x]);
    }
    api_req = API_URL + param_string;
    console.log("requesting: " + api_req);
    MakeJSONCallback(api_req);
}

function DescribeActions()
{
    api_request("DescribeActions", "ProcessDescribeActions", {})
}

function ProcessDescribeActions(API)
{
    var ERROR = API.ERROR;
    if (ERROR == "OK")
    {
        var api_actions = API.Actions;
        var i = 0;
        var output = "Actions: \r\n\r\n";
        while (i < api_actions.length)
        {
            output = output + api_actions[i].Name + "\r\n";
            i++;
        }
        alert(output);
    }
    else
    {
        alert("API Error" + ERROR);
    }
}

DescribeActions();

</script>

This example will ask the server for a list of actions, alert them in the browser once the response is received.

Notes on XML

  • If a simple array is part of the output (meaning a one-dimensional array whose indices are integers) than the XML output method will call every element of the array an <item>. This will not effect parent or children nodes in any way.
  • The root nodes of the XML document can be set with the $CONFIG['XML_ROOT_NODE'] variable. By default, it is simply "XML"
  • Use of this API is meant to be simple, so there will be no inline attributes to XML nodes. Parsing the XML can be accomplished by SimpleXML following this example to retrieve the "ERROR" response from the server:
$PostArray = array("OutputType" => "XML");
$APIRequest = new APIRequest($TestURL, $PostArray);
$APIRequest->DoRequest();
$XML_resp = simplexml_load_string($APIRequest->ShowRawResponse());
$XML_resp->ERROR

LINE and CONSOLE

  • LINE and CONSOLE both output the API's response in simple textual (humanized) lines.
  • Members of a sub_array are indented by 2 spaces.
  • Each line contains key: value.
  • LINE is the raw data, and CONSOLE is meant to be used via script/console to provide colorized output that may be easier to read.
  • Perhaps the easiest way to develop a DAVE action is to use script/console. For example, I could attempt to add a new user with script/api --Action=UserAdd --FirstName=Demo --LastName=TestMan. This should result in an easy-to-read error letting me know I need to provide a password.
> script/api --Action=UserAdd --FirstName=Demo -LastName=TestMan
DAVE_API_SERVER @ 127.0.0.1

api_requests_remaining: 995
Action: UserAdd
Params:
  Action: UserAdd
  IP: localhost
  OutputType: CONSOLE
  FirstName: Demo
ComputationTime: 0.0014028549194336
IP: localhost
ERROR: Please provide a Password
ServerName: DAVE_API_SERVER
ServerAddress: 127.0.0.1
Something went wrong with that request. Please try again.