Documentation deprecated: This documentation is no longer being updated as of 3.8.0. For up-to-date information, see the guide information in the IBM Developer Community and the endpoint reference in IBM API Explorer.

By using the Aspera Connect JavaScript API (v2.8+) and Aspera Node API you can build a simple web application that has the ability to browse a Node for content, setup transfers and operate the transfers through the Connect Plugin.  This allows you to offer your users a simple, branded user experience while utilizing Aspera technologies.

This guide will cover how to setup your Connect Server, create a Node user, create a web service and develop a frontend for your users.

Connect Server Setup

Connect Server 3.0+ is required for setting up Node.  If you have not already downloaded the appropriate version for your platform and run the installer on your server, please see your confirmation email for the download link or contact Sales for more information. You will also need to ensure you have a valid Aspera license that supports the use of Node.  For this example, we will use the username "aspera" for the system/transfer user. You will need to replace this with the appropriate values based on your setup.

Configure the Server

Once your server is running you need to configure it to enable the Node API.  To do this simply edit the aspera.conf file which is normally located at <INSTALLATION_PATH>/etc/aspera.conf.  Open that file in a text editor and add the following (use your server address, for this example we are using a server located at

<server>   <server_name></server_name>   <enable_http>true</enable_http></server>

The <server> section allows you to use the Node capabilities of an Aspera Connect Server.  Simply by adding this to the aspera.conf file you can give authorized users access to Node over the default transport of HTTPS, for this example we also enable HTTP by setting the enable_http to true.

Now that the aspera.conf file is updated you need to start Aspera Central (asperacentral) and the Aspera node daemon (asperanoded) services on your system.

If you plan to use the download_setup or upload_setup endpoints you mush have token generation setup on your system.  If you do not you will get an error.  If you have either of these messages in your log file you do not have token generation setup:

  • LOG: No encryption key supplied for token generation
  • ERR: Error from fasp_build_token(): Invalid argument[XX], internal error

To test that the Node API is available you can use the following calls to verify.  If you get a HTTP 200 response than the Node API is available.  For this example, you will need to change the server address to your server and use the proper port (if using a different one).  If you did not enable HTTP in the aspera.conf file you will need to use the HTTP call instead.

curl -i -X GET -k -i -X GET

Create a Node User

Now that we have our server running with the Node API we need to create a user who can access files under the system user.  To this we need to first make sure that a document root path has been defined either globally or for the system user.  To ensure that the document root path has been defined you need you need to check your aspera.conf, you should have something similar to the section below.  If you do not you can add it, or for more information on the aspera.conf file please read over the aspera.conf reference.


Your Aspera Connect Server installation offers a program for this purpose.  A program called asnodeasmin (asnodeadmin.exe in Windows) can be found in the <INSTALLATION_PATH>/bin/ folder.  To run this program use a command line prompt and execute the following command; be sure to replace the values with the value that you wish to use.

NOTE: On UNIX based platforms you need root privileges (sudo)

asnodeadmin -au <new_user_name> -x <system_user_name> -p <new_user_password>

For example, if we wanted to create a new Node User with name "testnodeuser", password "testpasswd" and on a system with a system user "aspera"; we would run:

asnodeadmin -au testnodeuser -x aspera -p testpasswd

To verify that our user was created successfully and that they are able to connect and perform operations we can run the following test commands.  The first operation will return information about the system.  The second /file/browse operation will return a file list of the server.  Be sure to use the proper server address that your server uses with the username and password you just defined.

curl -u testnodeuser:testpasswd -k -u testnodeuser:testpasswd -k -d '{"path":"/"}'

asnodeadmin Examples

The asnodeadmin program offers an easy command line tool for managing Node Users. The following commands are supported for manipulating Node Users

Change Password

asnodeadmin -mu usr1 -x aspera -p <NEW_PASSWORD>

List Users

asnodeadmin -l

Delete User

asnodeadmin -du <USER_NAME>

Create a Web Service

In this section you will create a web application in Java that exposes a method to browse the Node and a method to setup a download on the Node.This example uses Java with the Restlet and Apache HttpClient library. Depending on the requirements of your project, you can easily add more methods to your server. For other methods and instructions on their use, refer to the documentation of RESTful endpoints for the Node API.

  1. To begin, create a new project in your preferred IDE.  For this example, we are going to create a project called AsNodeAPIServiceProject.
  2. Once you have your project open, create a new class called AsNodeAPIService, which contains the main method. In AsNodeAPIService, define two resources: AsNodeBrowseResource (which has the path /node/browse) and AsNodeDownloadSetupResource (which has the path /node/setupdownload), both running on port 9099. The role of this main class is to route the user's requests to the appropriate resource that will effectively handle and process the requests.

    The two resources you just defined will do the following:

    1. Accept the HTTP request
    2. Retrieve the parameters they receive
    3. Make a REST request to the Node API using the Apache HTTPClient and send the JSON result back to the requester.
    Since the functionality of the two resources are similar, you can abstract them into a class called AbstractNodeAPIResource or code each one separately.
  4. Using this layer of abstraction, you can implement your AsNodeBrowseResource as the following:

    Your AsNodeDownloadSetupResource should look something like this:

  5. Now that you have coded the two endpoints that we are using for this example, you can compile and run the code. You can either run it directly in your IDE or generate the HAR file and launch the service with the following command:
    java -cp "asnodeapiservice.jar:org.restlet.jar:org.json.jar:org.restlet.ext.json.jar:httpclient-4.2.1.jar:httpcore-4.2.1.jar:commons-logging-1.1.1.jar:commons-codec-1.6.jar" AsNodeAPIService
    For Windows, use the following:
    java -cp "asnodeapiservice.jar;org.restlet.jar;org.json.jar;org.restlet.ext.json.jar;httpclient-4.2.1.jar;httpcore-4.2.1.jar;commons-logging-1.1.1.jar;commons-codec-1.6.jar" AsNodeAPIService

Create a Frontend

Now that the web service is running you need to create a frontend for your users to interact with.  In this example we are going to use HTML and JavaScript to create the frontend.  For this example we are going to keep the HTML basic.

To get the basics you can create a HTML page with two buttons, one for browsing and one for downloading, and an empty table that will be filled with the files and paths returned by the browsing operation.  The example HTML is seen below, you can see that the HTML uses jQuery (for DOM manipulation and AJAX calls) and asperaweb-2.js for accessing the Connect Plugin Library.


In our JavaScript we will need to make a call to the web service we created earlier.  To do this we can use the following code.  This code creates a JSON object with a member parameter which contains the REST call arguments that the web service will accept. The code then calls the service and waits for a JSON response which will either trigger the success or error function.


You can now create your browse function.  This function will build a JSON Object that will hold the browse parameters and call the service.  This example is basic and will just browse the root of the directory.  However, you can easily extend it to offer the user a customized experience by collecting data from the user and displaying that data by sending it in the JSON request, once a response is received indicating success it adds the data to a table in the HTML file, how you handle the returned data is up to you and what type of user interface you wish to design.


To provide insight into what is returned an example of the returned JSON is below.


Now that the user can browse the files that are on the Node you probably want to give them the ability to download a file. To do this you will use the following function. This function creates a transfer_request JSON that contains all the data needed to setup a transfer. Once the call is made it waits for a return JSON Object that will contain the transfer_spec used by the Connect Plugin to initiate the transfer, you will also need to add authorization:token to the JSON since Node does not include this by default. To start the transfer you would pass the transfer_spec to the download function which will talk to the Connect Plugin to initiate the transfer, or if the Connect Plugin is not installed help the user to install it.

Video player