REST API Query API

About

REST API Query API exposes a class and functions that make it trivial for other modules create and expose convenient functions that consume RESTful APIs.

How to use/implement REST API Query API

A module that implement the REST API Query API only need to implement a few things;

1. Define a class which extends rest_api_query. Usually only the constructor and some properties need to be overridden in order to set authentication credentials and the API's access point (base URL).

   For example:
   

   <?php
class foobar_api_query extends rest_api_query {
  // Only use the secure API
  protected $scheme = 'https';
  // The base path of the API is foobar.local/services/rest/version-3
  protected $host = 'foobar.local';
  protected $path = 'services/rest/version-3';
  // Foobar authenticates via BasicAuth using the API key as username and "api_token" as password.
  protected $password = 'api_token';
  function __construct($api_key = NULL) {
    $this->username = $api_key ? $api_key : variable_get('foobar_default_api_key', FALSE);
    $this->initialized = !empty($this->username);
  }
}
?>
2. Implement hook_rest_api_schemas() to tell REST API Query about the name and location of the above class and define the resource types exposed via the API in both singular and plural forms.
   <?php
function custom_rest_api_schemas() {
  $schemas = array();

  $schemas['foobar'] = new stdClass();
  $schemas['foobar']->class = 'foobar_api_query';
  // class foobar_api_query is declared in classes.inc
  $schemas['foobar']->file = 'includes/classes.inc';
  $schemas['foobar']->types = array(
    // SINGULAR => PLURAL
    'foo' => 'foos',
    'bar' => 'bars',
    'barry' => 'barries',
  );

  return $schemas;
}
?>
3. Implement API functions that invoke rest_api_query(). E.g. foobar_barries(), foobar_barry_load(), foobar_barry_save(), foobar_foo_update() etc. The body of these functions is usually a one-liner that is the same or very similar for all such API functions. These functions typically just wrap a wrapping function for rest_api_query_handle_api_function()
   <?php
function foobar_handle_api_function() {
  return rest_api_query_handle_api_function('foobar')->execute()->result;
}
// Gets the most recent Foo objects.
function foobar_foos($parameters) {
  return foobar_handle_api_function();
}
// Updates or creates a barry object.
function foobar_barry_save($barry) {
  return foobar_handle_api_function();
}
?>
   or call rest_api_query() directly
   <?php
// Gets the most recent Foo objects.
function foobar_foos($parameters) {
  // The Foobar API returns the list of foos as a property of the result.
  return rest_api_query('foobar', 'foo', 'index', $parameters, FALSE)->execute()->result->foos;
}
// Updates or creates a barry object.
function foobar_barry_save($barry) {
  // Let rest_api_query automatically execute the query and return the result.
  return rest_api_query('foobar', 'barry', 'save', $barry);
}
?>

The above examples are untested. Please contribute corrections in the issue queue.

Existing implementations, as examples

See the 2.x branches of the Redmine API and Toggl.com API modules for exiting implementations of the REST API Query API. These are useful examples.

Attribution

This module was originally developed by Palantir.net.

Downloads