That exploration will not unfold in this post, however. It could easily be an entire book unto itself.

Rather, I would like to focus specifically on ideas I’ve had about what a high level object oriented API for interacting with RESTful services might look like, and funnel those thoughts into the design and implementation of a plugin I’m developing for the Symfony framework, called sfRESTClientPlugin.

Audience and Scope

This post assumes at least casual familiarity with Web development. I will explore some general principles of the RESTful interaction paradigm, but only to the extent to which they inform the design direction of the plugin’s API.

Although all the code samples will be in PHP, it is my hope that the exercise will yield material valuable to people working with other software stacks.

The Fundamentals

Wikipedia offers a great article describing REST that is worth reading, if you would like a quick brush-up or introduction to the concept. I would describe REST as an “organic” extension to the model around which the World Wide Web itself was designed, as it wholly embraces a model composed of resources (text, images, videos, etc) that can be accessed using specific URLs.

I’ll be using the following assertion from the article as the springboard for my API design considerations (emphasis added to highlight the principal entities):

An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP). In order to manipulate these resources, components of the network (user agents and origin servers) communicate via a standardized interface (e.g., HTTP) and exchange representations of these resources (the actual documents conveying the information).

The API will therefore designed around the following discreet entities:

• Service
• Resource
• Client (or “user agent”)
• Request
• Response

Another design goal for the plugin is that it offers the integration mechanisms that developers familiar with Symfony (and other high-quality MVC frameworks) will find familiar, such as named routes, YAML project configuration, DRY design, and an environment-aware configuration cascade.

A Sneak Peak

At a certain point, examples speak more clearly than theories and principles. For the remainder of this post, I will talk about a sample REST service, which represents a “traditional” library — a collection of books.

The primary entities with which your site’s business logic will be dealing with are the services themselves, each which offer one or more resources. Each service is defined by a collection of properties that declare information such as its host name, the types of resources available from the service, authentication credentials, and perhaps smaller details like a port number, root URI, etc.

A sample configuration might look like this:

  [#!yaml]
  # config/rest_services.yml
  services:
    service_1:
      scheme  : https
      host    : exampleservice.com
      root_uri: /api

      resources:

        book:
          list: /books.xml
          item: /books/:id.xml

        author:
          list: /authors.xml
          item: /authors/:id.xml

The RESTful service in our example is located at https://exampleservice.com/api and offers two resource entities: book and author. These configuration values will be used to populate the properties of a sfRESTOriginService instance that represents the service.

Note that this configuration is defined under the key service_1. Here’s what some code that interacts with this service might look like:

  [#!php]
  $svc = sfRESTOriginService::getInstance( 'service_1' );

  // GET https://exampleservice.com/api/articles/34.xml
  $response = $svc->get( '@book?id=34' );

  // make sure we have a valid response
  if ( $response->isError() )
  {
    if ( $response->isStatusCode( sfRESTClient::STATUS_UNAUTHORIZED ) )
    {
      throw new Exception( 'Access to resource is unauthorized!' );
    }
    else
    {
      throw new Exception( 'An error occurred attempting to access the resource!' );
    }
  }

  // load the XML into a locally defined entity and manipulate it
  $book = new MyLocalBook();
  $book->loadFromXML( $response->getResponseXML() );
  $book->setTitle( 'A New Title' );

  // PUT https://exampleservice.com/api/articles/34.xml
  $svc->put( '@book?id=34', array(
    'data' => $book->serializeXml()
  ));

As the sample suggests, each service will be represented by a single instance.

Each service naturally supports the four HTTP methods used by REST: GET, POST, PUT, and DELETE, so requests of these method types are issued by invoking the corresponding class methods of a sfRESTOriginService instance.

The GET method requires only a URI, indicating the desired resource.

Each request to the service produces a response object, which offers access to the resource data in question. The response object also provides access to response information such as HTTP headers, the resource URL, the request method used for the query that created it, and the HTTP status code.

Each method must be performed against a particular URI, which must be specified, and the PUT and POST methods also require a data payload.

Parting Thoughts

This post is simply a starting point; a sketch. I will follow up shortly with another post outlining deeper use cases, such as using the POST method to create new resources, and dealing with resources of different data types, such as JSON, plain text, or even media files.

In the meantime, I welcome any thoughts or questions regarding this initial direction.

One particular matter I’m not so hot on from the examples above is the way in which resources are defined in the service configuration. I wonder if there isn’t some better way to express the resource configuration, and manage to still deliver the “named route”-like approach to specifying resource URIs shown in the sample code above.

Although these libraries were initially born for use in the Symfony MVC framework, the talented developers involved in the project have designed them to avoid any interdependencies with any of the other parts of the overall framework. This effort has resulted in components that may be used individually in any other PHP project without requiring the use of any of the rest of the Symfony framework.

The initial round of components include:

• YAML, a parser that translates data between YAML and native PHP arrays;
• Event Dispatcher, which provides a generic event dispatching framework; and
• Templating, which provides parameterized and scope-isolated templating functionality.

I’ll be keeping a keen eye on this project.

This “lazy hydration” of Propel’s looks like this:

  [#!php]
  // query all the author entities as a Creole ResultSet
  $rs = AuthorPeer::doSelectRS( new Criteria() );

  while( $rs->next() )
  {
    $author = new Author();
    $author->hydrate( $rs );
    echo "{$author->getLastName()}, {$author->getFirstName()}";
  }

The code above does the following:

1. it queries the database for all records in the author table, and loads it into a Creole ResultSet object.
2. enters a loop, iterating over each result (ie, table row) in the ResultSet, and with each of its records, it:
   1. creates a new, empty Author object
   2. hydrates the empty object with the data in the ResultSet‘s current row
   3. writes the author’s last and first name to the output buffer

In this way, only one Author instance is in use at any given time. Each iteration discards the previous instance and creates a new one.

But I hate it — it’s ugly and unwieldy.

This overt use of the ResultSet object is an awkward practice when using an ORM. The primary design goal of ORMs is to allow the developer to work at a higher level of abstraction than SQL queries and database result sets.

So what should it look like?

Assuming you’re not worried the query’s results might chew up all system’s RAM, the Propel API lets you get the job done like this:

  [#!php]
  foreach( AuthorPeer::doSelect( new Criteria() ) as $author )
  {
    echo "{$author->getLastName()}, {$author->getFirstName()}";
  }

For starters, this is a more concise block of code.

Secondly, this block of code focuses more directly on classes that are directly relevant to your application’s business logic.

Unfortunately, for all the theoretical loveliness it espouses, it consumes considerably more RAM since the data from each record of author table is loaded into unique instances of Author objects, which are all dumped into an array.

If the database only has ten authors, you won’t have any problems finding the RAM to instantiate all ten Author objects.

If you have tens of thousands of author records, on the other hand, it might be challenging enough to allocate enough RAM to store the entirety of the raw data generated by the database query, let alone to load that data into tens of thousands of Author object instances.

Propel’s “lazy hydration” approach sacrifices a little concision in return for some resource efficiency.

But I was writing many dozens of blocks of code like this, and seeing what is essentially the same lines of code dutifully repeated all over the place started to wear on me. I was even nesting these iterations, winding up with variable scopes that simultaneously contained variables named $authors_rs, $books_rs, and $whatever_else_rs.

I got fed up, so I decided to fix it.

I had started thinking about some other Symfony classes that managed to abstract Propel API quirks, and found inspiration in the sfPropelPager class. I decided to encapsulate all that into the sfPropelLazyHydrationIterator class, which implements PHP’s Iterator interface to provide the best of both worlds.

Let’s start simply:

  [#!php 1]
  // create a sfPropelLazyHydrationIterator
  $authors = new sfPropelLazyHydrationIterator('Author', new Criteria());

  foreach( $authors as $author )
  {
    echo "{$author->getLastName()}, {$author->getFirstName()}";
  }

The constructor requires two arguments: the name of the Propel model class, and a Criteria object. Internally, the object queries the database to retrieve a ResultSet. Using this object in a foreach() loop iterates through the database results using the same lazy hydration technique we looked at earlier.

Let’s take a look at a slightly more complex scenario, which uses a Propel 1.2 Connection for an in-transaction query:

  [#!php 1]
  // let's add a transaction to the mix
  $con = Propel::getConnection();
  $con->begin();

  try
  {
    // do some stuff to author records within the transaction...

    $authors = new sfPropelLazyHydrationIterator( 'Author', new Criteria(), $con );
    foreach( $authors as $author )
    {
      echo sprintf('%s, %s', $author->getFirstName(), $author->getLastName());
      $author->setLastAccessedOn( 'now' );
      $author->save( $con );
    }

    $con->commit();
  }
  catch (SqlException $sqle)
  {
    $con->rollback();
  }

But how does this all happen? Let’s look at an abbreviated version of this class:

  [#!php 1]
  class sfPropelLazyHydrationIterator
  implements Iterator
  {
    private $modelClassName;
    private $resultSet;

    /**
     * Contstructor.
     *
     * @param string $model_class_name
     * @param Criteria $c
     * @param Connection $con
     * @param string $peer_name
     */
    public function __construct( $model_class_name, $c, $con=null, $peer_name=null )
    {
      $this->modelClassName = $model_class_name;
      $this->modelPeerName  = empty($peer_name) ? $this->modelClassName.'Peer' : $peer_name;
      $this->resultSet      = call_user_func(array($this->modelPeerName, 'doSelectRS'), $c);
    }

    /**
     * Implements Iterator::current()
     */
    public function current()
    {
      if (false !== $this->resultSet->getIterator()->current())
      {
        return $this->createAndHydrateCurrent();
      }

      return false;
    }

    /**
     * Implements Iterator::next()
     */
    public function next()
    {
      if (false !== $this->resultSet->getIterator()->next())
      {
        return $this->createAndHydrateCurrent();
      }

      return false;
    }

    // ... other Iterator methods

    /**
     * Returns a hydrated instance of the appropriate model class, using
     * the row data at the ResultSet's current pointer position.
     *
     * @return mixed
     */
    protected function createAndHydrateCurrent()
    {
      $object = new $this->modelClassName();
      $object->hydrate( $this->resultSet );
      return $object;
    }

  }

The real work happens in the constructor and createAndHydrate() method. The latter is called by the Iterator interface implementations of the next() and current() methods (included in the code excerpt above).

This class is available in its entirety as part of the sfPropelLazyHydrationIteratorPlugin, which I have already published to the Symfony plugins site. The plugin is not, at the time of this writing, available as a PEAR package, but I intend to sort that out in the coming days.

Please note: the sfPropelLazyHydrationIterator presently only works with Propel 1.2.

Getting Really Lazy

And finally, let’s surrender fully to the laziness within — let’s look at super concision. We’ll add a new method to the AuthorPeer class:

  [#!php 1]
  class AuthorPeer extends BaseAuthorPeer
  {

    /**
     * Returns a sfPropelLazyHydrationIterator to allow iteration over retrieved
     * database results, utilizing "lazy hydration".
     *
     * @param Criteria $c
     * @param Connection $con
     * @return sfPropelLazyHydrationIterator
     */
    public static function doSelectLazy( $c, $con=null )
    {
      return new sfPropelLazyHydrationIterator('Author', $c, $con);
    }

    // ... other peer methods ...
  }

Now, we can iterator over all author records like so:

  [#!php 1]
  foreach( AuthorPeer::doSelectLazy(new Criteria()) as $author )
  {
    echo "{$author->getLastName()}, {$author->getFirstName()}";
  }

Whoever said you couldn’t have your cake and eat it obviously wasn’t terribly determined to be as lazy as possible.