Lesson 12: Using the OpenSocial REST API

This tutorial describes the usage of the OpenSocial API in context of an gadget from a gadget backend through a two-legged OAuth flow. For information and tutorials on how to use this API from an external website or client see VZ-Login.

The easiest way to access the OpenSocial REST or RPC API is with an OpenSocial client library. The client libraries handle to complete two- or three-legged OAuth flow (see OAuth_Use_Cases) and abstract the whole API communication.

The Client_Libraries article shows where you can download such client libraries and how you can configure them to work with VZ-Netzwerke.

Following are some examples on how to use the PHP library.

USER_ID is the OpenSocial ID (format www.vz.net:blaba, www.schuelervz.net:balhga, ...) of the user for which you want to perform this request (xoauth_requestor_id).

If you called your own backend from a gadget (see Lesson_10:_Interact_with_your_own_Backend for an example) and want to execute additional API request there, this user id should be in most cases the one you can retrieve from $_GET['opensocial_viewer_id'].

Please keep in mind to call the right API endpoint the user you are sending requests for (xoauth_requestor_id) as specified at REST

Retrieving user data

<?php
// Add the osapi directory to the include path
set_include_path(get_include_path() . PATH_SEPARATOR . '..');

// Require the osapi library
require_once "osapi/osapi.php";

// set logger to just output any debug information to the console or browser
osapiLogger::setLevel(0);
osapiLogger::setAppender(new osapiConsoleAppender());

$userId = 'USER_ID';

//create provider
$provider = new osapiVzOAuthProvider(osapiVzOAuthProvider::STUDIVZ);
$auth =  new osapiOAuth2Legged('CONSUMER_KEY', 'CONSUMER_SECRET', $userId);
//activate body hash
$auth->setUseBodyHash(true);
$osapi = new osapi($provider, $auth);

// Start a batch so that many requests may be made at once.
$batch = $osapi->newBatch();

$profile_fields = array(
    'aboutMe',
    'displayName',
    'lookingFor',
    'photos'
);

// Fetch the current user.
$self_request_params = array(
    'userId' => '@me',              // Person we are fetching.
    'groupId' => '@self',             // @self for one person.
    'fields' => $profile_fields       // Which profile fields to request.
);
$batch->add($osapi->people->get($self_request_params), 'self');

// Fetch the friends of the user
$friends_request_params = array(
    'userId' => $userId,              // Person whose friends we are fetching.
    'groupId' => '@friends',          // @friends for the Friends group.
    'fields' => $profile_fields,      // Which profile fields to request.
    'count' => 2          // Max friends to fetch.
);
$batch->add($osapi->people->get($friends_request_params), 'friends');

//execute the batch request
echo '<pre>';
print_r($batch->execute());
echo '</pre>';

Sending notifications

<?php
// Add the osapi directory to the include path
set_include_path(get_include_path() . PATH_SEPARATOR . '..');

// Require the osapi library
require_once "osapi/osapi.php";

// set logger to just output any debug information to the console or browser
osapiLogger::setLevel(0);
osapiLogger::setAppender(new osapiConsoleAppender());

$userId = 'USER_ID';

//create provider
$provider = new osapiVzOAuthProvider(osapiVzOAuthProvider::STUDIVZ);
$auth =  new osapiOAuth2Legged('CONSUMER_KEY', 'CONSUMER_SECRET', $userId);
//activate body hash
$auth->setUseBodyHash(true);
$osapi = new osapi($provider, $auth);

// Start a batch so that many requests may be made at once.
$batch = $osapi->newBatch();

$message = new osapiMessage(array($userId), 'this is the body', 'this is the title', 'NOTIFICATION');

$params = array(
	'userId' => $userId,
	'message' => $message,
);

$batch->add($osapi->messages->create($params), 'requestId');

//execute the batch request
echo '<pre>';
print_r($batch->execute());
echo '</pre>';