2. How to use the API

2. How to use the API

As we've seen in chapter Setting up your controller, you'll need to start with adding the LinkedinComponent and providing your application API_KEY and API_SECRET. That will initialize the plugin.

class MyController extends AppController {

	var $components = array('Linkedin.Linkedin' => array(
		'key' => 'YOUR API KEY HERE',
		'secret' => 'YOUR API SECRET HERE',
	));
	
}

So how do we interpret the API in conjunction with the plugin?

The plugin provides 2 important methods for interacting with the LinkedIn API:

• call($path, $args);
• send($path, $data, $type = 'json');

Where call() will be used for retrieving data using GET and send() will be used to POST data. Always referrer to the linkedin developer documentation: http://developer.linkedin.com/docs/DOC-1258 for more information about the API methods.

call($path, $args)

You can retrieve any linkedin data you want, for example retrieving profile information of a specific connection and show all related recommendations.. or showing their connections, network updates etc.. endless possibilities!

• @param path: You'll notice that the first parameter is the API path.. In this case the 'people/~' stands for profile information of the connected user. See http://developer.linkedin.com/docs/DOC-1002
• @param args: The second parameter are the arguments to provide (formatted as an array). Internally the plugin will format it to a valid query encoded string. The arguments in this case are profile fields of the data we want to receive.

example retrieving profile information @see http://developer.linkedin.com/docs/DOC-1002

function profile() {
	$this->set('response', $this->Linkedin->call('people/~',
			   array(
			        'id',
			        'picture-url',
			        'first-name', 'last-name', 'summary', 'specialties', 'associations', 'honors', 'interests', 'twitter-accounts',
			        'positions' => array('title', 'summary', 'start-date', 'end-date', 'is-current', 'company'),
			        'educations',
			        'certifications',
			        'skills' => array('id', 'skill', 'proficiency', 'years'),
			        'recommendations-received',
			   )));
}

In this simple example we'll send the response to the view profile.ctp, where $response contains the result data. You can simply test the result in your view with debug($response) or pr($response)

send($path, $data, $type)

The send() method works slightly different. It uses the POST method instead of GET. It doesn't really send POST variables like key/value pairs, but instead it sends the raw body with header data via POST. You can define the body content and the header content-type.

• @param path: Again the first parameter is the API path.. In this case the 'people/~/mailbox' stands for sending a message by the current user to connections set in the data parameter See http://developer.linkedin.com/docs/DOC-1044
• @param data: The second parameter is the data as array. NOTE: It is important to follow the format of the API..
• @param type The content-type of the data. Internally the data array will be encoded to a valid format by this type parameter. In this example we'll set type to 'json'

example sending a message @see http://developer.linkedin.com/docs/DOC-1044

function send( $id ) {

	if (!empty($this->data)) {
	
		$result = $this->Linkedin->send('people/~/mailbox', array(
			'recipients' => array('values' => array(
				array(
					'person' => array(
						'_path' => '/people/id=' . $id,
					),
				),
			)),
			'subject' => $this->data['subject'],
			'body' => $this->data['body'],
		));
		
	}
	
}

note The third parameter type isn't set in this example. In this case we want the data to be encoded as json.. this is the default so we don't need to provide it here.