Was this helpful?

This topic explains the simplest way to wrap a Node.js application in an API proxy using the management UI.


Chances are, the first Node.js app you ever created was an HTTP server that responds to requests with "Hello World!" The simplest way to try out Node.js on Apigee Edge is to do something very similar. With just a few mouse clicks, you'll have a functioning, proxied Node.js HTTP server running on Edge. After that, you can use the code editor in the UI to modify the Node.js app, add additional Node.js files, add policies, and so on. 

Creating the sample Hello World! API proxy

This section explains how to create an Edge API proxy that interacts with a Node.js HTTP server. The Node.js HTTP server code is already written for you and is automatically deployed to Edge when you follow these simple steps.

If you have not done so, you need to set up an account on Apigee Edge before you can try out this example.

  1. Log in to the Apigee Edge management UI
  2. From the APIs menu, select API Proxies.
  3. In the API Proxies summary page, click +API Proxy.

  4. In the New API proxy dialog, select New Node.js
  5. From the Node.js Server Type options, select Node.js Sample "Hello World". (We'll discuss the other Node.js Server Type, the "Integrated API BaaS" sample later in this topic.)
  6. Provide a Display Name for the proxy. You can just enter Hello.
  7. Provide a Project Base Path. If you specified Hello as the display name, then the path /hello is populated automatically. 
  8. Add a version number /v1 to the path. API versioning is a best practice. The new Project Base Path is:

  9. Optionally, provide a Description.

  10. Click Build.

Edge builds the proxy. When the build completes, the hello proxy appears in the API Proxies summary page. Select API Proxies from the APIs menu to see the API Proxies summary page, shown below:

Invoking the hello proxy

When you call the hello proxy, the Node.js application executes automatically, responding with "Hello, World!". Note that unless you specified otherwise, the Node.js application is deployed to the environment called test. Here's the basic call using Curl (substitute your organization name for myorg). 

$ curl http://myorg-test.apigee.net/v1/hello
Hello, World!

Viewing and editing the Node.js code

Let's look at the Node.js code that was added to the API proxy. Go to the summary page for the Hello World proxy and click Develop.

This opens the Develop view which includes a code editor. You can edit the code there directly.


For example, change the response from Hello, World! to something else, like Hello, Node!, then click Save. The proxy is saved and redeployed.

Finally, re-invoke the proxy to verify the change:

$ curl http://myorg-test.apigee.net/v1/hello
Hello, Node!

Adding new Node.js source files in the UI

The management UI lets you add additional Node.js source files to the proxy. You can create them directly in the UI or import them from your file system.

Only one Node.js source file is designated to be the main file.  The main file is the one you would execute from the command line to run a Node.js application. The main file is specified in the proxy's target endpoint definition file using an element called <ScriptTarget>, as explained in Invoking an imported Node.js file and in Adding Node.js to an existing API proxy. In these out-of-the-box examples, the correct target endpoint definition is created for you. 

To create a new Node.js resource file:

  1. In the Develop view, select New Script from the New menu.
  2. In the Add Script dialog, select the file type Node and name the script.
  3. Click Add


The new, blank Node.js file opens in the editor. You can cut and paste your code into the file. The file also appears in the Scripts section of the Navigator.

Importing Node.js files from your filesystem

To import a Node.js file from your filesystem to the proxy:

  1. In the Develop view, select New Script from the New menu. 
  2. In the Add Script dialog, click Import Script.
  3. Use the file tool to select your Node.js file.
  4. The file's name is added to the dialog, but you can change it if you wish.
  5. Click Add. The file appears in the Scripts section of the Navigator and opens in the editor.
  6. Click Save
If you want to invoke the imported file, an extra step is required, as explained in the next section.

Invoking an imported Node.js file

You can't simply invoke a newly imported or created Node.js file. The reason is that Edge requires that one Node.js file be the main file. The main file is specified in the <ScriptTarget> element of the Target Endpoint definition. To specify which file is the main Node.js file, do the following:

  1. Under Target Endpoints in the Navigator, click the name of the target endpoint (usually called default). 
  2. In the Code editor, edit the <ScriptTarget> element by changing the <ResourceURL> to reflect the name of the file you wish to be the main Node.js file. For example, if you wanted a file called hello-world.js to be the main file, you'd enter: node://hello-world.js in the ResourceURL element.
  3. Click Save.

At this point, you can invoke the file with whatever proxy path you used before. For example, we've been looking at the Hello World! example, where the base path v1/hellois specified. However, you can change the base path by editing the Proxy Endpoint.

Recall that the Proxy Endpoint defines how clients call your API. When a client calls the API with the new base path, processing is routed to the Target Endpoint, where the main Node.js file is specified.

  1. Under Proxy Endpoints in the Navigator, click the name of the proxy endpoint (usually called default). 
  2. In the Code editor, edit the <HttpProxyConnection> element by changing the <BasePath> to whatever name you wish. For example, if the current <BasePath> is v1/hello and you wanted it to be v1/my-node-file, change the <BasePath> element like this:

  3. Click Save
  4. Invoke the proxy using the new base path, like this:

    $ curl http://myorg-test.apigee.net/v1/my-node-file
    Hello, World!

Understanding the Integrated API BaaS sample

Now that you've seen the Hello World sample, let's briefly look at the other out-of-the-box selection: the Integrated API BaaS sample.

The basic steps for creating and invoking this sample are the same as the Hello World! sample. The API BaaS sample is a little more complex, however. 

The Integrated API BaaS sample integrates two Node.js frameworks to create a simple API service. One API call simply returns a string embedded in the code, and the other retrieves data from an external service and returns that data in the response.

The frameworks used in this sample are Express and Argo. Both are web application frameworks. Express is a web application framework that is very popular among Node.js developers. Argo is another web application framework that is an open source project sponsored by Apigee.

To create this sample proxy:

  • Follow the same steps for creating the Hello World! proxy, but choose the Node.js application type called Node.js Sample: "Integrated API BaaS" sample.

Here is the source code that is deployed with this proxy:

var argo = require('argo');
var express = require('express');

var app = express();

var proxy = argo()

app.get('/hello', function(req, res) {
  res.send('Hello from Express');

app.all('*', proxy.run);

In this code, Express is used to specify the GET call, which simply sends back text when the API is called with /hello. The Agro method executes as well. It returns data from the site https://api.usergrid.com. The build() method prepares Argo's request event listener. The listener is currently accessible by calling the run method on the object returned from the build method. 

If you call this proxy with the /hello path, it returns "Hello from Express!":

$ curl http://myorg-test.apigee.net/v1/data-service/hello
Hello from Express!

If you call this proxy without /hello, it runs the argo proxy, which grabs information from the api.usergrid.com site:

$ curl http://myorg-test.apigee.net/v1/data-service

You can read more about the Argo framework at its repository in GitHub.

More about running Node.js applications on Apigee Edge

Like all Node.js applications, Node.js applications running on Apigee Edge run in a single thread of control. There is no need (and in fact no ability) to start another thread, or synchronize variables between threads. Since Node.js enforces non-blocking programming, a single script can support thousands of concurrent requests because the script gives up the CPU whenever it has to wait for something, and it is notified later when it happens.
As discussed previously, to use Node.js on Apigee Edge, you need to specify a main Node.js script file. This script must be configured to handle incoming requests, which you typically do by using the http or https modules, creating a client, and so on. (If the main script is not configured this way, it will simply execute and exit after it is deployed.) Within Apigee Edge, each Node.js application script is started from the beginning when the proxy is deployed, and stopped when the proxy is undeployed. In between it will wait for new requests and process them.

Next Steps

You can also create and deploy standalone Node.js applications directly from your file system. The next topic, Deploying a standalone Node.js app, explains how to use the apigeetool command to deploy a Node.js app from the command line.



Add new comment

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.