The SocialHub API module provides functionality for easily accessing the SocialHub Publisher API, automatically taking care of security and authentication.

Installation and setup

Install the SocialHub API module as usual.

Visit admin/config/services/socialhub and provide the site-wide configuration of the SocialHub App ID, the Secret Key and the API URL to make use of.
These values can be found on the administrative dashboard of your App configuration.

Module structure

Usage

This module provides no working features out of the box, only an API layer which makes it easier for developers to use the SocialHub Publisher API easier without caring about doing the actual request, the authentication or the generation of the request signature. It also provides an easy way to define own API callbacks for certain features of the SocialHub which need to push data back.

Making an API request

The easiest way to use the API module is by using the static SocialHub class in SocialHub.php. It contains detailed information about its usage and also catches and logs any exceptions for you (and returns FALSE in those cases). Using the SocialHub class, the side-wide configuration will be used for making API requests.

Example:

SocialHub::createPost(array(
  'contentSourceLink' => url('node/' . $node->nid, array('absolute' => TRUE)),
  'payload' => array(
    'body' => $node->body,
    'image' => $node->field_image,
  ),
));

If you need to catch exceptions your self or you need multiple settings for the requests, have a look at the global socialhub() function. This factory function will initialize the needed API classes with the settings you specified to override.
socialhub($app_id = NULL, $secret_key = NULL, $api_url = NULL)

Example:

try {
  socialhub(NULL, NULL, $my_api_url)->post()->create(array(
    'contentSourceLink' => url('node/' . $node->nid, array('absolute' => TRUE)),
    'payload' => array(
      'body' => $node->body,
      'image' => $node->field_image,
    ),
  ));
}
catch (SocialHubApiException $e) {
  socialhub_log_exception($e);
}

Defining a callback route

Callback routes can be defined by implementing hook_socialhub_callback_info() (see socialhub.api.php).

Example:

function my_module_socialhub_callback_info() {
  $callbacks = array();
  // Define a callback to react upon post status updates.
  $callbacks['mymodule/posts/status'] = array(
    'update' => 'my_module_callback_status_update',
  );
  return $callbacks;
}

function my_module_callback_status_update($request_data) {
  // Do something as soon as a post is published.
  if ($request_data['postStatus'] == SocialHub::POST_FINISHED) {
    my_module_do_something();
  }
}

Altering API requests and responses

There are two hooks described in the socialhub.api.php file:

// For altering incoming and outgoing requests before they take effect.
hook_socialhub_request_alter(SocialHubApiRequest &$request)

// For altering request response data before it is returned.
hook_socialhub_response_alter(&$response, SocialHubApiRequest $request)

Debugging

When you activate the Verbose mode of the Advanced options on the admin/config/services/socialhub page, all outgoing and incoming API requests will be logged by watchdog (with dblog enabled to admin/reports/dblog).
If you have the devel module enabled too, it will output you the full request and response data using it's dumping functions.