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 existing implementations of the REST API Query API. These are useful examples.

An even simpler implementation that serves as a good example is Topsy.com API module. It is less complete than Toggl.com API or Redmine API, but it does not require create an account on Toggl.com or install Redmine if you want to get it working.

Commercial support

The author of this module is available for hire. Contact Bevan.

Attribution

This module was originally developed by Palantir.net.

Project Information

Downloads