Was this helpful?

Introduction

This topic explains how to add a Node.js application to an existing proxy on your local file system and how to deploy the proxy to Apigee Edge. 

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:

<TargetEndpoint name="default">
    <Description/>
    <Flows/>
    <PreFlow name="PreFlow">
        <Request/>
        <Response/>
    </PreFlow>
    <HTTPTargetConnection>
        <URL>http://weather.yahooapis.com</URL>
    </HTTPTargetConnection>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
</TargetEndpoint>

The <HTTPTargetConnection> element specifies the URL of the backend service, the Yahoo Weather API.

However, in the case of Node.js, the Node.js application itself is the target. You specify this with <ScriptTarget> in the apiproxy/targets/default.xml file. 

Instead of the target using the <HTTPTargetConnection> element to specify the URL of a backend service, the Node.js application is referenced directly using a <ScriptTarget> element, like this:

<TargetEndpoint name="default">
    <ScriptTarget>
         <ResourceURL>node://server.js</ResourceURL>
    </ScriptTarget>
    <PreFlow name="PreFlow">
        <Request/>
        <Response/>
    </PreFlow>
</TargetEndpoint>

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:

var http = require('http');
console.log('node.js application starting...');
var svr = http.createServer(function(req, resp) {
    resp.end('Hello, Node!');
});

svr.listen(process.env.PORT || 9000, function() {
    console.log('Node HTTP server is listening');
});
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:

/apiproxy/proxyName.xml
/apiproxy/proxies/default.xml
/apiproxy/targets/default.xml
/apiproxy/resources/node/server.js

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:

  1. 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.

argo 0.4.9 
usergrid 0.10.7 
async 0.2.9 
express 3.4.8 
underscore 1.5.2 
volos-oauth-apigee 0.0.2 
volos-quota-apigee 0.0.2 
volos-cache-memory 0.0.3

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.

Deploy the Node.js app to Apigee Edge

Before you deploy, you'll need to know your organization name, user name, and password for your Apigee Edge account. You need this information to correctly form the deployment tool command.

Here's the command. It assumes (with the -d flag) that you are in the root directory of your proxy. If your proxy is called foo, then enter this command from the foo directory:

$ apigeetool deployproxy -u username -p password -o org -e test -n hellonode -d .
For information on what each of the command flags mean, do this:

$ apigeetool deployproxy -h

For a quick summary:

  • -n This flag lets you specify the name of the proxy that will be created when the app is deployed. You'll see this name in the management UI.
  • -d  Specifies the root directory of the API proxy. 
  • -o, -e, -u, and -p specify the organization name, deployment environment, user name and password.
That's it. Your Node.js app is wrapped in an API proxy, deployed to Edge, and executed. It is waiting for requests and ready to be tested.

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.

$ curl http://org_name-test.apigee.net/
Hello, Node!

View the new proxy in the management UI

Log in to your your Apigee Edge account and go to the API Proxies page. You will see the proxy called "hellonode" listed there.


Click on "hellonode" to view details about the proxy. In the Develop view, you can see the source code you uploaded, add policies, edit flows, and so on.



Next steps

For information on debugging Node.js applications running on Apigee Edge, see Debugging Node.js proxies.

Get help

For help, see Apigee Customer Support.

コメント

It would be nice if one can determine whether a request came from https or http. Others use the "X-Forwarded-Proto": "https" header and there is built in support in express via app.enable('trust proxy');

Hi there Joseph - thank you for taking the time to provide your comment. We've put the issue on our doc update radar. Agreed - it would be great to provide some best practices on this topic.

Thank You for your reply jhasegawa. I just found out I can restrict to https by having only the secure in the Proxy Endpoints.

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.