Make sure to follow the API forums so you're informed about changes and updates as soon as we post them! Just go to the API forum page or Developer announcements page and click the Follow button.

Example PHP Class

(Requires PHP 5) This is only an example - it's probably not production-ready, so please use at your own risk.

class Populi{
    //Set to the correct URL for your college
    protected $api_url = 'https://YOUR_SUBDOMAIN_HERE.populiweb.com/api/index.php';
    
    //You can set this to a valid access token - if null, you'll need to call login() before calling doTask()
    private $api_token = null;
    
    public function login( $user_name, $password ){
        $post_params = [
            'username' => $user_name,
            'password' => $password
        ];
        
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $post_params);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_URL, $this->api_url);
        $response = curl_exec($curl);
        curl_close($curl);
        
        if( $response !== false) {
            // Use SimpleXML to put results into Simple XML object (requires PHP5)
            $xml = new SimpleXMLElement($response);
            if( isset($xml->access_key) ){
                $this->api_token = (string)$xml->access_key;
            }
            else{
                throw new PopuliException("Oops! Please enter a valid username/password.", 'AUTHENTICATION_ERROR');
            }
        }
        else{
            throw new PopuliException("Oops! We're having trouble connecting to Populi right now... please try again later.", 'CONNECTION_ERROR');
        }
    }
    
    public function logout(){
        $this->api_token = null;
    }
    
    //By default, we'll attempt to parse the response into a SimpleXML object and return that.
    //For certain tasks, though, (like downloadFile), you'll want the raw response and will need to set return_raw to true.
    public function doTask( $task, $params = array(), $return_raw = false ){
        if( !$this->api_token ){
            throw new Exception("Whoops! Please call login before trying to perform a task!");
        }

        $header = [
            'Authorization: ' . $this->api_token
        ];

        $post_params = [
            'task' => $task
        ];
        
        foreach($params as $param => $value){
            if( is_array($value) ){
                foreach($value as $array_key => $array_value){
                    if( is_array($array_value) ){
                        foreach($array_value as $array_value_key => $array_value_value){
                            $post_params["{$param}[{$array_key}][{$array_value_key}]"] = $array_value_value;
                        }
                    }
                    else{
                        $post_params["{$param}[{$array_key}]"] = $array_value;
                    }
                }
            }
            else{
                $post_params[$param] = $value;
            }
        }
        
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $post_params);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_URL, $this->api_url);
        $response = curl_exec($curl);
        curl_close($curl);
        
        if( $curl !== false ){
            if( $return_raw ){
                return $response;
            }
            else{
                // Use Simple XML to put results into Simple XML object (requires PHP5)
                try{
                    $xml = new SimpleXMLElement($response);
                }
                catch(Exception $e){
                    throw new PopuliException('Problem parsing the XML response: ' . $e->getMessage());
                }
                
                if( $xml->getName() == 'response' ){
                    return $xml;
                }
                else if( $xml->getName() == 'error' ){
                    throw new PopuliException((string)$xml->message, (string)$xml->code);
                }
                else{
                    //Woah - response or error should always be the root element
                    throw new PopuliException('Problem parsing the XML response: invalid root element.');
                }
            }
        }
        else{
            throw new PopuliException('Could not connect to Populi.', 'CONNECTION_ERROR');
        }
    }
}

class PopuliException extends Exception{
    /*******************************************************************************************
     *  We have our own variable since we don't feel like using numeric error codes
     *  Should be one of:
     *      AUTHENTICATION_ERROR - Couldn't login to the API (bad username/password)
     *      BAD_PARAMETER - You called a task using parameters it didn't like
     *      CONNECTION_ERROR - Thrown if we can't connect to Populi 
     *      LOCKED_OUT - Your user account is blocked (too many failed login attempts?)
     *      OTHER_ERROR - Default generic error
     *      PERMISSIONS_ERROR - You aren't allowed to call that task with those parameters
     *      UKNOWN_TASK - You tried to call an API task that doesn't exist
    *********************************************************************************************/
    public $populi_code = null;
    
    public function __construct($message, $populi_code = 'OTHER_ERROR'){
        parent::__construct($message);
        $this->populi_code = $populi_code;
    }
    
    public function getPopuliCode(){
        return $this->populi_code;
    }
}

Usage:

$populi = new Populi();
$populi->login(YOUR_USERNAME, YOUR_PASSWORD);
echo htmlentities($populi->doTask('getRoles', array(), true));
usleep(1000000); // Wait 1 second before making another call, to avoid rate limiting