Web Services Integration Framework

Web Service Integration Framework (WSIF)

Created by Deeson Online

This is an API type module - you won't need it unless you install another module that depends on it.

About

When connecting Drupal to an external service there are a number of repeated tasks that any good web service integration requires.

1. List if the webservice is running on the report status screen
2. Take the connection to the webservice down globally if it stops responding or runs slow.
3. Periodically check the web service when it is globally off to see if it is back and working correctly.
4. Singleton and Factory patterns for resource handling.
5. Integration with standard Drupal framework (logging and exception handling, caching etc).

The goal of the Web Service Integration Framework (WSIF) is to provide a standardised structure for other modules which talk to web services so it does in a standard fashion.

How to use this module with your web services module

1. Extend and wrapper the API.

You will generally have an API for your webservice, typically a class file that must be instantiated. Instead of instantiating this directly we will wrapper it in a wsif container.

Assuming your module is called mymodule and your service API class is called MyService and is stored in a file called MyService.class.inc this provides the following starting files for your integration module:
- mymodule.module
- mymodule.info
- myservice_wrapper.class.inc
- MyService.class.inc

The myservice_wrapper.class.inc will include a class with a definition like this:

 class MyServiceWrapper extends MyService implements WSIFInterface { 

  /**
   * Check the connection to the api.
   *
   * @return bool
   *   TRUE if connection is OK or FALSE otherwise.
   *   Note that for slow connections this may time
   *   out and throw an Exception which should also
   *   be accounted for.
   *
   * @see wsif_cron()
   */
  public function wsifCheckConnection() {
    try {
      // Try getting some data from the service, should this fail,
      // the service must be unavailable.
      $response = $this->getData();
      return TRUE;
    }
    catch (Exception $e) {
      watchdog_exception('myservice', $e);
    }

    // We've been unable to receive data.
    return FALSE;
  }

  /**
   * Provide the current version of your API here.
   *
   * @return string
   *   Version information.
   */
  public function wsifGetVersion() {
    try {
      return $this->getVersion();
    }
    catch (Exception $e) {
      watchdog_exception('myservce', $e);
    }
    return 'Unknown';
  }

}

You must then provide two functions inside this called wsifCheckConnection() and wsifVersion(). The first is run periodically by cron when the service is flagged as off and will switch it back on if it returns TRUE. The second is purely informative and displays the version on the report status screen.

Within mymodule.module you should define the following hooks:

 /**
   * Implements hook_wsif_info().
   */
  function mymodule_wsif_info() {
    return array(
      'myservice' => array(
        'name' => t('My Service'),
        'description' => t('My Service integration'),
        'machine_name' => 'myservice',
        'extra' => '',
      ),
    );
  }

  /**
   * Implements hook_wsif().
   */
  function mymodule_wsif() {
    return new MyServiceWrapper();
  }

The hook_wsif_info hook informs wsif about your service. The hook_wsif() hook is the factory method for your API and should return a new version of the API. The wsif module will only call this once per session to build an instance of the connection that gets passed around.

2. In your code, to obtain an instance of your API you would now use the wsif function

     $api = wsif_get_api('myservice');

If the service is unavailable, this will generate an Exception of type WSIFUnavailableException. You should allow this WSIFUnavailableException to propergate up the stack to the point at which it makes sense to handle it. For example, when the user tries to perform an action which needs the service you could then tell them it did not work as the service is unavailable.

   try {
     mymodule_update_record($user, $data);
   }
   catch (WSIFUnavailableException $e) {
     watchdog_exception('mymodule', $e);
     drupal_set_messge(t('Unfortunatley our partner service is currently unavailable, please try again later'));
   }

Dependencies

There are no dependencies for this module but using the variable and variable_admin modules are highly recommended as this will provide a configuration form for each web service at admin/config/system/variable

Example of use

The responsys module makes use of the wsif module to provide a robust integration with the Responsys Email marketing tool. http://drupal.org/project/responsys