Introduction

Preparing your development environment

In this topic, we assume you already have a proxy development environment set up on your local system and that you want to integrate a Node.js application into it.

If you don't have an existing proxy on your system, you can always download the Apigee Node.js samples from GitHub. The sample proxy in node-samples/apigee/hello follows the same organizational pattern discussed in this topic.

The basic structure of a proxy application that includes a Node.js app follows the pattern shown in the figure below, with a base /apiproxy folder and sub-folders for resources, targets, and proxies. The apiproxy/resources/node folder is where Node.js files must be placed. The other folders contain XML files that define proxy and target endpoints, proxy flow, conditional flows, and so on. For a more complete description of the API proxy structure, see API proxy configuration reference.

Just remember that any Node.js code that is part of the proxy must be placed under /apiproxy/resources/node. That's where Edge expects to find it when it is deployed.

Specify the Node.js target with ScriptTarget

The key to integrating Node.js into a proxy is specifying the <ScriptTarget> element in the target endpoint's XML file. In the proxy file structure, this XML file is located in apiproxy/targets. By default, the filename is default.xml.

For context, consider that the target endpoint usually points to a backend service of some kind, such as the Yahoo Weather API, or any API. In the case of the weather API, the most basic target endpoint definition looks like this:

The only parameter to <ScriptTarget> is <ResourceURL>. The <ResourceURL> parameter must always be prefixed with node://, followed by the name of the main Node.js script. And, as noted previously, the main script must reside in /apiproxy/resources/node.

A TargetEndpoint can define either an HTTPTargetConnection or a ScriptTarget, but not both.

The main script is the name of the script that you'd normally pass to the node command. As long as the main Node.js script uses the http module to listen for incoming requests, it will respond whenever an API call is routed to the target.

For the purpose of this example, here is the source code for the main Node.js file, called server.js. It's the basic HTTP server that returns "Hello World!" when it receives a request:

Note how the port number is coded as a conditional in the http.listen() method. Coding the listening port in this way, so that it can be obtained from a system variable, if defined, is considered a best practice by Apigee.

To summarize, assuming that the main Node.js application is implemented in a file called server.js, and that the endpoint configurations are both named default.xml, then the API Proxy containing the Node.js script has the following structure:

Prepare to deploy the application

Most Node.js apps have dependency files and include a package.json file in the base directory. In this case, the best practice is to run the npm utility to ensure that the top-level node_modules directory is populated with the dependencies before you deploy. If there are any remote dependencies that are not included in node_modules, your Node.js application will not run on Edge.

You can easily retrieve all dependencies onto your file system using the npm utility:

From the base directory of your Node.js application, run:

$ npm install

or

$ npm update

When the dependencies are installed, you are ready to deploy your proxy to Edge.

The following modules are pre-installed on Apigee Edge and are available for use in your deployed Node.js apps; however, if you want to run and test your apps locally, you'll have to install these dependencies on your system.

To override the version of a pre-packaged module, you must expicitly package the required version of the module in your Node.js app. Modules are resolved by name beginning with the API proxy scope and then expanding to the environment, organization, and Apigee Edge-side scopes.

Test the new API proxy

You have just added a Node.js app to an existing API proxy and deployed the proxy to Apigee Edge! To test it, run this cURL command. We assume the default base path (/) is used (base path is specified in the proxy endpoint configuration file). Be sure to substitute your organization name for org_name. If you do not have cURL installed, you can enter the URL in a browser.