Login if you already have an account



Create a new account. join us!



Need some help? Check out our forum.

March 9, 2012 vprakash@miegoapps.com

Extend Your API

Server Extensions are server side functions that execute from a REST URL request. Server extensions can be used for a number of things:

  • Validate user registration from a link that is sent in an email
  • Create custom objects or response data on the fly from data persisted on your API
  • Populate or clear out data from your API on demand
  • Provide testing capabilities for your API on demand
  • Anything you can dream of that you want from an URL request

At this time, we support extensions written in JavaScript. We are working on implementing CommonJS support which will make all the power and benefits of that standard available to you; and you will also shortly be able to implement server extensions in Java if you wish.

Server extensions are executed upon invocation of a HTTP Request, and have full access to all of the HTTP headers and request body.

The object which is passed to the server extension contains the following:

httpMethod: the HTTP method (eg. GET, POST, PUT, DELETE, HEAD)

httpRequestUri: the exact request URI, relative to your application’s root (eg. /ff/resources/Celebrity/xyzabc345123def)

httpParameters: A map of the request parameters

httpHeaders: A map of the request headers

httpCookies: For convenience, a map of the cookies from the Cookie request header

httpContent: A map corresponding to the JSON content supplied in the request body, if any

ffUser : the guid of the logged-in user.

Creating a Server Extension


Following on from the event handler example which sent an email with a link to click on to newly-registered users, here we show how to make that link actually activate the user when it is clicked. Save this code in a file called UserRelatedExtensions.js in the ff-scripts directory. The script does the following:

  • Checks that a guid parameter has been supplied
  • Checks that an object with this guid exists in the /ActivationRequests collection
  • Checks that the activation request object refers to a valid FFUser
  • Sets the user status to active
  • Removes the activation request object
  • Returns some html to the client saying that the account has been activated
exports.verifyRegistration = function (json) {
var data = JSON.parse(json);

r = ff.response();

if (! data.httpParameters['guid']) {
r.result = "<HTML><BODY><H2>Activation guid not supplied</H2></BODY></HTML>";
r.responseCode = "400";
r.statusMessage = "Activation guid not supplied";
r.mimeType = "text/html";


guid = data.httpParameters['guid'];

activateRequest = ff.getObjFromUrl("/ActivationRequests/" + guid);
if (! activateRequest) {
r.result = "<HTML><BODY><H2>Could not find activation guid</H2></BODY></HTML>";
r.responseCode = "404";
r.statusMessage = "Could not find activation guid";
r.mimeType = "text/html";


user = ff.getUser(activateRequest.userGuid);
if (! user) {
r.result = "<HTML><BODY><H2>Could not find user to activate</H2></BODY></HTML>";
r.responseCode = "404";
r.statusMessage = "Could not find user to activate";
r.mimeType = "text/html";


user.active = true;

print("nnt*** User account " + JSON.stringify(user) + " has been activatednn");

r.result = "<HTML><BODY><H2>Your account has been activated</H2></BODY></HTML>";
r.responseCode = "200";
r.statusMessage = "Your account has been activated!";
r.mimeType = "text/html";

[/fancy_pre_box] You will note that you have complete control over the response codes, data and the statusMessage in the response returned as well.

Define the Extension in your FFDL


In order for the FatFractal Emergent Framework to be aware of your Server Extension, you need to add it to your FFDL configuration as follows:

CREATE EXTENSION /verifyRegistration UNSECURED  AS javascript:var f = require ('scripts/UserRelatedExtensions'); f.verifyRegistration (FF_EXTENSION_REQUEST_DATA_JSON);

For more detail – see the FFDL Reference Server Extensions section.

[/fancy_pre_box] This defines a url for your extension (http://<domain>/fatfractal.com/<application>/ff/ext/verifyRegistration) and instructs the backend to call the verifyRegistration function that is included in a file in your scripts directory called UserRelatedExtensions.js with the information contained in your url request.

NOTE: This extension is created with the (optional) UNSECURED keyword. By default, your custom server extensions will only execute if invoked by a logged-in user. In this case however, we wish the extension to execute for a user who is not logged in – the UNSECURED keyword declares this.