Todd Appleton - May 5, 2016
nodejs-banner.png

DreamFactory supports V8js, Node.js, PHP, and Python for server-side scripting. In a previous blog post I showed how to create a custom scripting service using V8js. Below, I’ll show you the steps to enable and use Node.js scripting in your DreamFactory environment. It’s recommended that you use DreamFactory 2.1.2 (or greater) where Node.js is fully supported. We also have a detailed wiki tutorial you can use as a technical reference.

The first step is obviously to make sure Node.js is installed on your system. In my case I’m on OS X Yosemite so I can do a ‘which node’ and see that the path to Node.js is /usr/local/bin/node.  ‘node -v’ shows that I have v4.4.2. If you don’t get a valid path go to https://nodejs.org to for instructions on downloading and installing Node.js for your system.

Once you know the path to the node executable you need to set it in your DreamFactory .env config file. This file is found under the main dreamfactory directory. For example, in a Bitnami setup it’s htdocs/.env. If you installed from GitHub it would normally be dreamfactory/.env. Edit this file and set DF_NODEJS_PATH to point to your node location. Make sure you delete the ## to uncomment this line.

DF_NODEJS_PATH=/usr/local/bin/node

You may need to add quotes around the path, especially for Windows. This allows for spaces in the path.

DF_NODEJS_PATH="c:Program Filesnodejsnode.exe"

To force a reload of config you can use the following command. Run it from the same directory as the .env file.

php artisan config:clear

Now you’re ready to start writing your Node.js scripts. Next we’ll create the same math service as the previous blog post but this time using Node.js.  The script is functionally the same as the V8js version. The only difference is how it loads the lodash library. For V8js there’s a file lodash.min.js on the local file system which is loaded with require(‘lodash.min.js’). For Node.js lodash is installed using npm then loaded with require(‘lodash’).

0.png
  • Go to the Services tab in the admin console.
  • Click Create and set Service Type to ‘Custom Scripting Service’.
  • Set the name to ‘math’. This will be part of the URL when you call the service.
  • Set the label to ‘Math’.
  • Click the Config tab and set the Scripting Engine Type to ‘Node.js’.
  • Paste the following code into the Content text area, then click Create Service to save your new service.
var params, required, n1, n2, resource, result;

var lodash = require("lodash");

if (event.request.method !== "GET") {
    throw("Only HTTP GET is allowed on this service.");
}

// get query params from request
params = event.request.parameters;

// get resource, /math —> "", /math/add —> "add"
resource = event.resource;
if (resource !== "") {
    // check for required params
    required = ["n1","n2"];
    lodash._.each( required, function( element ) {
        if (!params.hasOwnProperty(element) || !params[element]) {
            throw( "Missing '" + element + "' in paramsn" );
        }
    });
    n1 = Number(params.n1);
    n2 = Number(params.n2);
}

switch (resource) {
    case "":
        // /math means return all supported resources
        result = {"resource": ["add", "subtract", "multiply", "divide"]};
        break;
    case "add":
        result = {"result": n1 + n2};
        break;
    case "subtract":
        result = {"result": n1 - n2};
        break;
    case "multiply":
        result = {"result": n1 * n2};
        break;
    case "divide":
        if (!n2) {
            throw("Divide by zero error.");
        }
        result = {"result": n1 / n2};
        break;
    default:
        throw("Invalid or missing resource name.");
        break;
}

return result;

The script uses lodash, so before you can run it you need to use npm to install lodash. Your script can include any other node modules you need in this same manner.

For Bitnami installs it’s best to run npm from the htdocs directory:

npm install lodash

You can use the -g option if you like:

npm install -g lodash

Now that lodash is installed you can call this service from the REST API. Using your REST client of choice, make the following GET request. Replace everything before /api/v2 with your instance base URL. You can use HTTP basic auth or pass an authenticated session token in the API call.

GET https://127.0.0.1:8080/api/v2/math

For example, with cURL:

curl -i -k -3 -X GET "https://127.0.0.1:8080/api/v2/math" 
-H "X-DreamFactory-Session-Token: your-session-token"

The URL ends with the service name, ‘math’. Since there is no resource specified like add or subtract, the scripting service will return a list of available resources.

{
    "resource": [
    	"add",
		"subtract",
		"multiply",
		"divide"
	]
}

To add two numbers, make the following request. Now the URL also includes the resource ‘add’.

GET https://127.0.0.1:8080/api/v2/math/add?n1=3&n2=5

The script returns the sum of n1 and n2 in JSON format.

{
    "result": 8
}

If you want to create a Swagger service definition you can follow the steps from the previous blog post. If you need some examples of both event and custom scripting with Node.js check out the wiki Tutorials. These should help get you started.