API Library Suggestions

My plans are to continue developing API libraries for CI in my free time. One thing I am going to do is combine the YouTube and Dropbox libraries into the same github repo since they do share some common code in oauth_helper. That would mean only having to update things in one place as opposed to several in the current repo structure.

That being said, I am starting to run out of decent API ideas. I think the next one I will tackle is the NetFlix API but beyond that I am really not sure.

What API libraries would you like to see implemented in CodeIgniter?

CodeIgniter Dropbox API.

Well folks, I have done it again. You guys seem to enjoy my YouTube API and now I officially present my CodeIgniter Dropbox API.

Here is the github repo for it.

Now for some documentation.

As with the YouTube API the first step in getting this sucker setup is getting a developer key by visiting https://www.dropbox.com/developers/apps. There you will setup your new application and they will give you an 'App Key' and 'App Secret'. Put these values into a config file so that we can reference them later. Now download the API files from my github repository and place them into your application folder.

1. My trusty oauth_helper.php file belongs in the helpers directory
2. dropbox.php is the API file and belongs in the libraries directory

Once they are in place we need to authenticate the API with your dropbox account. We do this using OAuth so you will need to create a controller and add the following methods.

public function request_dropbox()
{
   $params['key'] = $this->config->item('dropbox_key');
   $params['secret'] = $this->config->item('dropbox_secret');
       
   $this->load->library('dropbox', $params);
   $data = $this->dropbox->get_request_token(site_url("welcome/access_dropbox"));
   $this->session->set_userdata('token_secret', $data['token_secret']);
   redirect($data['redirect']);
}
    
public function access_dropbox()
{
   $params['key'] = $this->config->item('dropbox_key');
   $params['secret'] = $this->config->item('dropbox_secret');
       
   $this->load->library('dropbox', $params);
       
   $oauth = $this->dropbox->get_access_token($this->session->userdata('token_secret'));
       
   $this->_store_in_db($oauth['oauth_token']);
   $this->_store_in_db($oauth['oauth_token_secret']);
}

Now a few lines there need some explanation. In request_dropbox my get_request_token call should have a URL to the access_dropbox method right below. Basically we want the dropbox site to redirect there once the request step is finished. On the next line we store the token secret because we will need that in the access_dropbox method later. Finally we redirect to the provided redirect (this will take the user to the dropbox site).

In the access_dropbox method not too much is different. Make the get_access_token call and pass in the token secret. You should get back an array with an 'oauth_token' value and an 'oauth_token_secret' value. You should store those with your user as they are what you will use to make authenticated request on that users behalf.

Provided those went well we can begin actually fiddling with the API (it should be noted that most calls from the API will return PHP objects as a response). Here is an example of how to load the API with all of the data we have generated.

$params['key'] = $this->config->item('dropbox_key');    
$params['secret'] = $this->config->item('dropbox_secret');
$params['access'] = array('oauth_token'=>urlencode($this->_get_from_db()),
                          'oauth_token_secret'=>urlencode($this->_get_from_db()));
       
$this->load->library('dropbox', $params);

Note that the access parameter is an array with keys 'oauth_token' and 'oauth_token_secret' and that the value of each of these keys is urlencoded. Make sure you mimic this same layout otherwise you risk running into issues with your authenication. Finally load the library with the parameters.

Once the library is successfully loaded you can now make some calls. There are several to choose from the simplest is 'account', so calling:

$this->dropbox->account();

Should return a php object with various account data in it. Most of the methods return a php object there are only two that do not.

$this->dropbox->thumbnail($destination, $path, $size='small', $format='JPEG', $root='dropbox')
$this->dropbox->get($destination, $path, $root='dropbox')

The reason these don't return an object is because they actually write a file to the $destination path. The only time these will return anything useful is if an error has occurred.

Another useful method is the add method which will add a file to your dropbox.

$this->dropbox->add($dbpath, $filepath, $root='dropbox');

Here $dbpath is the path within your dropbox (including file name) where the file will go, and $filepath is the path to the file on your server. Unless you know what the $root parameter is for I would just leave it alone.

To finish things off here is the list of the remaining methods. Most are simply for manipulating files in your dropbox folder a few are for getting information on files in your dropbox.

$this->dropbox->metadata($path, $root='dropbox');
$this->dropbox->link($path)
$this->dropbox->copy($from, $to, $root='dropbox');
$this->dropbox->create_folder($path, $root='dropbox');
$this->dropbox->delete($path, $root='dropbox');
$this->dropbox->move($from, $to, $root='dropbox');

That's it every one of those should be decently documented in the code. I should point out that I am not doing anything specatular with CodeIgniter so the library should work with 2.0 and the old 1.7.2. I hope you guys enjoy, it was a lot of fun writing it. Let me know in the comments or post on the github repo if you have any problems.

[EDIT] Here is the link to the Dropbox web api: https://www.dropbox.com/developers/web_docs