Was this helpful?

    This feature is currently in public beta.

    Apigee Edge enables developers to deploy and run Node.js applications in a scalable, cloud-based environment.

    This support for Node.js application enables developers to:

    • Build API proxies entirely in Node.js using a framework like Argo.
    • Build new APIs that proxy other APIs using frameworks like Argo, Express, Geddy, Hapi, and others.
    • Build "mash-ups" and composite services using existing APIs and web services.
    • Rapidly prototype new APIs using a web framework like Express.
    • Manage your Node.js application with Apigee Edge policies, to add API keys, OAuth, caching, rate-limiting, and many other out-of-the-box capabilities.
    • Get detailed operational and content-based analytics on the traffic to and from your Node.js application.

    Management UI quick start for Node.js

    Apigee Edge enables you to write, deploy, invoke, and test Node.js applications in a Web browser-based configuration environment.

    1. First, set up an account on Apigee Edge.
    2. Log in to the Apigee Edge management UI
    3. Select APIs > API proxies from the the main menu. A list of API proxies is displayed.
    4. To generate an API proxy to host your Node.js application, click the + API Proxy button

    5. Configure the API proxy. The New API Proxy menu displays a set of options for the proxy that you are creating.
      1. Select Node.js.
      2. From the Node.js options, select Node.js "HelloWorld" Sample.
      3. Provide a Display Name for your API proxy.
      4. Provide a Project Base Path. This is a URI path used to create the network address for this application.
      5. Provide an optional Description.
      6. Click Build.

      New API Proxy configuration form

      Once API Services has generated the new API Proxy, the Overview page displays high-level information, including metadata and analytics, related to your new API proxy.

      API proxy overview for a Node.js application

    6. To view the code of the Node.js application, select the Develop view.

      As shown below, the Develop view enables you to view, edit, and save a Node.js application. You can paste Node.js scripts directly into the browser-based environment, then save and deploy them.

      Node.js application in the Apigee Edge Management UI

    Invoking the application

    The API proxy hosting your Node.js application is deployed in the test environment. It is available over the network at the URL generated for your organization. You can invoke the application from a Web browser. For example, if your organization were called 'developerz', then you would invoke the Node.js with this address: http://developerz-test.apigee.net/v1/helloworld

    Or using curl:

    $ curl http://developerz-test.apigee.net/v1/helloworld
    Hello, World!
    
    Just substitute the name of your organization. (To get your organization name, look under User Settings.)

    Visualizing the runtime using the Trace tool

    Apigee Edge provides a Trace tool that enables you to view the application as it interacts with request and response messages.

    1. In the API proxy editor, select the Trace view.

    2. In the Trace view, select the Start Trace Session button. (The button will turn red and display the Stop Trace Session option.)

    3. With the trace session running, click the Send button. The tool will submit a request to the address that displays under URL.

      The messages that you submit result in transactions, which display in the left-hand menu.

      As shown below, the Trace tool displays the inbound request and the response to the client app.Debugging a Node.js application in the trace tool 

      The Trace tool also offers a script output panel, which displays HTTP headers, payload content, and any logging messages from the Node.js application.

    Log output from a Node.js application in Trace tool

    Download the Node.js sample apps

    You now know the basics of working with Node.js in the Apigee Edge management UI. You can write (or copy-and-paste) your own Node.js application in the code view to start building custom Node.js applications.

    A set of sample Node.js applications is available on GitHub.
     

    To obtain the samples, clone the repository using the following command:

    $ git clone https://github.com/apigee/node-samples

    You can deploy the samples by following the CLI quick start for Node.js, or by copying and and pasting the Node.js for the samples directly into the browser-based development environment described in the quick start above.

    CLI quick start for Node.js

    You can also develop Node.js applications on your local machine, test them locally, and then upload them to Edge API Services for execution. This section demonstrates the usage of the apigeetool command-line interface (CLI).

    This quick start assumes that you have an account on https://enterprise.apigee.com.

    You can sign up for a free account at https://accounts.apigee.com/accounts/sign_up.

    Step 1: Install the platform tools

    The Apigee Edge Tools are a Python package that is maintained in GitHub. You obtain them by cloning the repo as follows:
    $ git clone https://github.com/apigee/api-platform-tools.git
    

    This copies the contents of the repo to your local machine under api-platform-tools. Navigate to the install directory.

    $ cd api-platform-tools

    Install the tools

    The command below installs the tools on your machine in a standard location such as /usr/local/bin. On a Macintosh or Linux, you will need to use sudo to run this tool as root, although setup.py has a number of other options in case you cannot do this.

    $ cd api-platform-tools
    $ sudo python setup.py install

    Step 2: Create a directory for your new application. In this example, call it nodeapp

    $ cd ..
    $ mkdir nodeapp
    $ cd nodeapp

    Step 3: Using your favorite text editor, create a file called server.js and insert the following:

    var http = require('http');
    
    var svr = http.createServer(function(req, resp) {
      resp.writeHead(200, { 'Content-Type': 'text/plain' });
      resp.end('Hello, World!\n');
    });
    
    svr.listen(9000, function() {
      console.log('The server is listening on port 9000');
    });
    

    Step 4: Deploy the new application to your organization on Apigee Edge:

    Using the organization name, username and password for your account on https://enterprise.apigee.com:
    $ apigeetool deploynodeapp -n hello -d . -m server.js -o org_name -e test -u username -p password

    Step 5: Invoke the application

    Substitute the name of your organization for {org_name}:

    $ curl http://{org_name}-test.apigee.net/
    Hello, World!

    Deploy an existing Node.js application to Apigee Edge

    Preparing the Application

    When deploying an existing Node.js application, you specify:

    • The Node.js application's root directory
    • The name of the main script

    The deployment tool will package the specified directory and its contents, and pushes the resultant package to Apigee Edge.

    Apigee Edge is flexible about the structure of the Node.js application, but there are a few things to watch out for.

    If your application uses NPM, it will have a package.json file in the base directory.

    To ensure that the top-level node_modules directory is populated with all the applications' dependencies, run:

    $ npm install 

    or

    $ npm update

    from the base directory of your Node.js application.

    If your application defines remote dependencies, then it will not run on Apigee Edge.

    The following modules are pre-installed on Apigee Edge and are available for use in your Node.js apps:
    argo 0.1.8 
    usergrid 0.10.5 
    async 0.2.9 
    express 3.2.6 
    request 2.21.0 
    underscore 1.4.4

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

    As part of deployment, you'll also have to identify the main script. The main script is the name of the script that you'd normally pass to the node command. This script must be in the base directory of your Node.js application.

    Deploying a Node.js application using apigeetool

    The command:

    $ apigeetool deploynodeapp

    is used to deploy an existing Node.js application to the Apigee Edge.

    When you invoke this tool, it does the following:

    • Generates an API proxy configuration bundle to house the Node.js application
    • Packages the Node.js application any associated NPM modules
    • Imports the API proxy configuration bundle to the specified organization on Apigee Edge using the Edge management API.
    • Deploys the API proxy to an environment, activating the Node.js application on Apigee Edge and making it available over the network

    The apigeetool takes the following options:

    apigeetool deploynodeapp -n [name] -o [organization] -e [environment]
             -d [directory name] -m [main script file]
             -u [username] -p [password]
             -b [base path] -l [apigee API url] -z [zip file] -i -h
    -o The name of your organization on enterprise.apigee.com
    -e The name of the environment (typically 'test' or 'prod') where you want to deploy the Node.js application
    -n The name of the API proxy
    -d The path to the directory called /apiproxy that contains the API proxy configuration files and the Node.js application
    -m Main Node.js script name, which should be at the top level of the directory
    -u The username for your account on enterprise.apigee.com
    -p The password for your account on enterprise.apigee.com
    -b An optional deployment base path (defaults to /)
    -l The base URL of the Edge management API (optional, defaults to https://api.enterprise.apigee.com)
    -z The name of the ZIP file to save (optional for debugging)
    -i A flag to import only, without deploying to an environment
    -h Print this message

    For example, imagine that you have a directory called nodeapp that contains a Node.js application with a main script named server.js. The following command will deploy this application to the "test" environment of the Apigee Edge organization "testorg":

    $ apigeetool deploynodeapp -n nodeapp -d nodeapp -m server.js
      -o {org_name} -e test -u {myname} -p {mypass}

    After deployment, the application will be available at the top-level of your Apigee Edge environment. For instance, if your organization is named "testorg" then you would invoke the application at the following URL:

    http://testorg-test.apigee.net/

    Finally, if you need to deploy multiple applications to the same organization and separate them by URI path, use the "-b" argument to "apigeetool," as follows :

    $ apigeetool deploynodeapp -n nodeapp -d nodeapp -m server.js
      -o {org_name} -e test -u {myname} -p {mypass} -b /nodeapp

    Add a Node.js application to an API Proxy

    Every Node.js application runs on Apigee Edge as a component of a standard API proxy. This section describes how to add a Node.js application to an API Proxy.

    Typical API Proxy

    The minimal API proxy has the following directory structure:

    /apiproxy/{APIProxy}.xml
    /apiproxy/proxies/{proxy}.xml
    /apiproxy/targets/{target}.xml

    For a complete description of the API proxy structure, see API proxy configuration reference.

    For working sample API proxies, see Using the samples.

    Node.js Components

    The Node.js application is added as a ScriptTarget in the TargetEndpoint configuration. Instead of the target having an HTTPTargetConnection element that specifies the URL of a backend service, the Node.js application is referenced as a ScriptTarget element. This substitutes the Node.js application for a remote backend service URL.

    For example, instead of:

    <TargetEndpoint name="default">
      <HTTPTargetConnection>
        <URL>http://weather.yahooapis.com</URL>
      </HTTPTargetConnection>
    </TargetEndpoint>
    

    Use:

    <TargetEndpoint name="default">
      <ScriptTarget>
        <ResourceURL>node://hello.js</ResourceURL>
      </ScriptTarget>
    </TargetEndpoint>

    The only parameter is ResourceURL. ResourceURL must always be prefixed with node://, followed by the name of the script that will run when the API Proxy is deployed.

    The second component is the Node.jsscript itself. As long as the target script uses the http module to listen for incoming requests, it will be invoked whenever an API call is routed to the target. This script must be stored under the /apiproxy/resources/node directory in the API Proxy configuration package.

    Assuming that the Node.js application is implemented in a single 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/APIProxy.xml
    /apiproxy/proxies/default.xml
    /apiproxy/targets/default.xml
    /apiproxy/resources/node/server.js

    Advanced ScriptTarget Configuration

    You can use the ScriptTarget element to pass command-line arguments and environment variables to a Node.js script::

    <TargetEndpoint name="default">
      <ScriptTarget>
        <ResourceURL>node://hello.js</ResourceURL>
        <EnvironmentVariables>
          <EnvironmentVariable name="NAME">VALUE</EnvironmentVariable> 
        </EnvironmentVariables>
        <Arguments>
          <Argument>ARG</Argument>
        </Arguments>
      </ScriptTarget>
    </TargetEndpoint>

    Node.js Reference

    Module Status Notes
    assert Supported  
    buffer Supported  
    child_process Disabled An exception will be thrown if an attempt is made to spawn a sub-process. However, "fork" is supported for spawning sub-scripts.
    cluster Disabled cluster.isMaster will return true, and other methods are not implemented
    crypto Partial support Random and HMAC functionality is supported. Remainder is unimplemented.
    dns Partial support dns.lookup is supported. All else is not implemented.
    domain Supported An exception will be thrown if an attempt is made to spawn a sub-process
    dgram Supported Attempts to listen for incoming datagrams will generate an exception.
    events Supported  
    fs Disabled Filesystem access is restricted to the directory where the script was launched: the /resources/node directory.
    http Supported The virtual host and path for incoming requests is specified in the API Proxy, not by the HTTP module. See below for details.
    https Supported Creating an "https" server behaves identically to an "http" server. TLS parameters work differently than in regular Node. See below for details.
    module Supported  
    net Attempts to listen for incoming TCP connections will generate an exception. os Partial Not all methods will return the same values that they return in a typical Node.js environment.  
    path Supported  
    module Supported  
    process Partial support Functionality to manipulate user ID, group membership, and working directory is not supported.
    punycode Supported  
    querystring Supported  
    readline Disabled There is no standard input for scripts running on Apigee Edge.
    repl Disabled There is no standard input for scripts running on Apigee Edge.
    module Supported  
    STDIO Supported Standard output and error are routed to a log file within the Apigee Edge infrastructure. See below for more information. There is no standard input for scripts running on Apiogee Edge.
    stream Supported  
    string_decoder Supported  
    timers Supported  
    tls Supported TLS parameters work differently than in regular Node. See below for details.
    tty Disabled There is no standard input for scripts running on Apigee Edge.
    url Supported  
    util Supported  
    vm Supported  
    zlib Supported  

    Scripts, Instances, and Environment

    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.

    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, assuming that it used the "http" or "https" module to listen for requests, it will wait for new requests and process them.

    Apigee Edge does not support the "cluster" module, which allows Node.js applications to control when additional copies of an application are started and stopped, and to communicate with them. In the parlance of the "cluster" module, all Node.js applications are considered to be the "master."

    However, Apigee Edge does deploy multiple instances of each application — two in most cases, although the system may be configured to run more if necessary.

    That means that Node.js applications running inside Apigee Edge, like all Node.js applications, must assume that they will be processing many different requests "in parallel" using a single thread of control. However, the application must not assume that it is the only copy running in the world, and it must not assume that there is some way to communicate with the other copies.

    HTTP and HTTPS

    All Node.js applications running in Apigee Edge must use the "http" or "https" module to listen for incoming requests. (Of course, you can deploy a script that doesn't, but it'll just exit and that will be that.)

    The "listen" method of the HTTP/S modules in Node takes a "port" as a parameter. This argument is required in Node, but Apigee Edge ignores this parameter. Instead, the API proxy that the Node.js script runs inside specifies which "virtual hosts" it listens on, and the Node.js application uses those same virtual hosts, just like any other Apigee Edge proxy.

    The apigeetool deploynodeapp command generates an Apigee Edge proxy wrapper around the Node.js application. When deployed, the Node.js application listens on the

    default

    virtual host defined for the environment. So the URL for a Node.js application will be http://{org_name}-{env_name}.apigee.net.

    Like other Apigee Edge applications, if the proxy application is set up to listen on the secure virtual host, then it will accept incoming requests using HTTPS. Currently, more advanced setup, including custom CNAME support and custom TLS certificates, requires assistance from Apigee.

    In addition to receiving incoming traffic, Node.js applications inside Apigee Edge may use the HTTP and HTTPS modules to make outbound requests like any other Node.js application. These modules work just as they always do inside Node.js.

    However, if you use custom SSL certificates or trust stores, the Apigee Edge support works differently.

    TLS/SSL

    For incoming requests, the following options are provided:

    • If the API proxy is configured to listen on the "default" VirtualHost, then requests are accepted over HTTP.
    • If the API proxy is configured to listen on the "secure" VirtualHost, then it will accept requests over HTTPS. The URL will be under the "apigee.net" domain, and a "wildcard" SSL certificate for *.apigee.net will be used.

    As long as apps make requests to the apigee.net domain, then the SSL certificate will validate normally.

    To use custom SSL certificates for inbound traffic, see Apigee Support at the Support Portal.

    For outgoing requests, Node.js support in Apigee works a little bit differently than it does in regular Node.js:

    (Outgoing requests over TLS work the same way whether they are HTTPS requests initiated using the https module or raw TCP sockets opened using the tls module.)

    By default, outgoing connections are validated against a predefined set of trusted root CA certificates. (This is the same default behavior as Node 0.10.)

    If rejectUnauthorized is set to false on the options object passed while creating a connection, then Apigee Edge will not validate the outgoing connection, and will instead connect to any endpoint that supports TLS. (Again, this is the same as Node 0.10.)

    To customize the list of trusted certificates that the client uses for TLS connections, a Java key store (.jks) file must be created that contains the appropriate certificates, and passed using the truststore argument. This replaces the ca argument used in "regular" Node.js.

    To make a TLS or HTTPS connection using a client SSL certificate, a Java key store (.jks) file must be created that contains the certificate and secret key that the client should use. It must be passed using the keystore argument, and the passphrase must be passed in the passphrase argument. This replaces the key, cert, and passphrase options in "regular" Node.js.

    Get help

    For help, see Apigee Customer Support.

    Help or comments?

    • Something's not working: See Apigee Support
    • Something's wrong with the docs: Click Send Feedback in the lower right.
      (Incorrect? Unclear? Broken link? Typo?)