Amplify.js

Request Component

The amplify.request component sets out to make data retrieval more maintainable. It does this by separating the definition of a request from the actual implementation of requesting the data. The definition of the request is only responsible for deciding the caching strategy, server location, data type, decoders, headers, etc. While the actual requestor code only needs to know a request ID. This allows for a data layer which can make your application much easier to test and more agile to change.

Request Define API

The role of amplify.request.define is to allow you to focus on only defining the implementation of retrieving data. The API for amplify.request.define can be very simple, but also has numerous optional parameters that you can leverage, including some that you can provide custom implementations of your own.

Define a Request

amplify.request.define( string resourceId, string requestType [, hash settings ] )

• resourceId: Identifier string for the resource
• requestType: The type of data retrieval method from the server. There is currently one built in requestType (ajax), but you can also define your own.
• settings (optional): A set of key/value pairs that relate to the server communication technology.
  • Any settings found in jQuery.ajax()
  • cache: Providing different caching algorithms for the request and response
    • boolean: Cache the data in-memory for the remainder of the page load
    • number: Cache the data in-memory for the specified number of milliseconds
    • string: Persistent client-side cache using amplify.store
      • "persist": Will use the first available storage type as default
      • "localStorage", "sessionStorage", etc. ... 
  • decoder: A way to parse an ajax response before calling the success or error callback. There is currently one built in decoder (jSend), but you can also define your own. By default no decoder is used unless you set it.
    • "jsend": A specification on how JSON responses should be formatted

Example Usage

amplify.request.define( "getContactDetails", "ajax", {
  //Amplify will replace {id} with data passed to it
  url: "/Contact/Details/{id}", 
  dataType: "json",
  type: "GET", 
  //Response will be cached for 15 seconds
  cache: 15000     
});

Request API

Once you've defined your request, then the next step would be to go ahead and call the amplify.request method. Thankfully, most of the hard part was defining the definition of the request, so calling amplify.request is fairly straightforward.

Simplified Request

amplify.request( string resourceId 
  [, hash data [, function callback ]] )

• resourceId: Identifier string for the resource
• data (optional): an object literal of data to be sent to the resource
• callback (optional): a function to call once the resource has been retrieved

Example Usage

amplify.request( "getContactDetails", 
  //Amplify will resolve url to "/Contact/Details/4"
  { id: 4 }, 
  function( data ) {
    console.log( data );
  });

Request with Hash Settings

amplify.request( hash settings )

• settings
  • resourceId: Identifier string for the resource
  • data (optional): Data associated with the request
  • success (optional): Function to invoke on success
  • error (optional): Function to invoke on error

Example Usage

amplify.request({ 
  resourceId: "getContactDetails",
  //Amplify will resolve url to "/Contact/Details/4"
  data: { id: 4 }, 
  success: function( data ) {
    console.log( data );
  },
  error: function( message, level ) {
    console.log( level + ": " + message );
  }
});

Sample Application

Now we will update the sample application from above and swap out the call to $.ajax() to use amplify.request instead.

var hackerNews = (function( $, undefined ) {
  var pub = {};
 
  pub.init = function() {
    //...
 
    //Define getNews AJAX JSONP request in Amplify
    amplify.request.define( "getNews", "ajax", {
      url: "http://api.ihackernews.com/page" + 
        "?format=jsonp", 
      dataType: "jsonp",
      cache: 30000
    });                
  };
     
  //...
     
  function getNews( callback ) { 
    //Request for news from Amplify        
    amplify.request({
      resourceId: "getNews",
      success: function( data ) {
        if ( callback ) callback ( data );
      },
      error: function( message, level ) {
        console.log( level + ": " + message );
      }
    });        
  }
     
  //...
     
  return pub;
}( jQuery ));
 
hackerNews.init();
hackerNews.getAndDisplayNews();

You can view, run, and edit the above source code from jsFiddle.

We first defined what the request will look like and placed that in our init method. We define the request as getNews, use the built in ajax type, and then pass some options which include common $.ajax() settings such as url and dataType, but also includes a amplify.request specificcache setting where we will cache the response of the request for 30000 milliseconds (30 seconds).

After defining our request with amplify.request.define, we then swapped out the $.ajax() code that was in the getNews method and replaced it with amplify.request referencing the resourceIdwe previously defined, a success callback, and an error callback method.

With caching now on when the user clicks on the Refresh button there will be a 30 second period where no actual ajax request is being made to the server. You can verify this using your web developer tools in your browser. Once the cache has been cleared after 30 seconds, then the real request will proceed to the server and return fresh results that will be in-turn cached for another 30 seconds.

By making these two small changes the application still works as it did before and we didn't have to change any other code. The power of Amplify is in having the definition adapt with changes while leaving the request functionality untouched. Just think what might happen if the backend switched to web sockets instead or instead of JSON being returned it was XML. Towards the end of this article we will take another look at the power of making this abstraction.

Benefits

• Separate out the definition from a request from the actual request for data from the server
• Ability to provide alternative caching and decoding implementations

http://msdn.microsoft.com/en-us/magazine/hh147623.aspx

http://amplifyjs.com/