Endpoints

At present the following endpoints are available to use (in alphabetical order):

• card
• cardcomments
• cardtags
• collection
• comment
• deck
• deckcard
• event
• eventcards
• eventtype
• eventuser
• group
• organisation
• tag
• topic
• user
• username
• vote

The special endpoints session and oauth relate to login requests and 3 legged oauth requests specifically.

Creating endpoints

Endpoints are created by creating a subclass of PHPFrame_RESTfulController, this should reside in a php file named after the endpoint, residing in the src/controllers/api/ directory. The class itself should have the following signature (using Card as an example):

<?php
class CardApiController extends PHPFrame_RESTfulController

Implementing verbs/actions

You implement the HTTP verb handlers by specifying functions named after the verb. E.g. to implement a post handler use this template (be sure to include phpdoc style comments in order for the api to be self documenting via endpoint/usage calls):

<?php
/**
* Short description of the action. Some more detailed text about the action
* 
* @param string $param1 Some text describing the first parameter
* @param int $param2 Some text describing the second parameter
*
* @return object Description of the returned object.
*/
public function post($param1, $param2)
{
    //some code to create new object
    $obj = array('param1'=>$param1, 'param2'=>$param2);
    //some code to save to database
    $some_mapper = new PHPFrame_Mapper('MyClassName', $this->db(), 'table_name');
    $obj = $some_mapper->insert($obj);

    return $this->handleReturnValue($obj);
}

Any request parameters in the GET or POST body will automatically be assigned to any similarly named function parameter, but you can also get any specific request parameter:

<?php
$param1 = $this->request()->param('param1');
$all_request_params = $this->request()->params();

Endpoint access

The database has a table api_methods which specifies which api endpoints are accessible and though which access methods. This table has the fields:

Field name	Description	Allowed values
method	the endpoint	Any string representing the endpoint/action e.g. card/post
oauth	an integer describing whether oauth calls are supported	0 = No oauth, 1 = both 2-legged and 3-legged, 2 = only 2-legged, 3 = only 3-legged
cookie	an integer describing whether session based clients (browsers) are supported	0 = None, 1 = unauthenticated sesssions, 2 = authenticated sessions

It is important to add the relevant database entries to this table if you add or modify any endpoints.