Overview

Getting Started with the Node API

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.

Aspera's Node API provides a RESTful interface for full control of IBM Aspera High-Speed Transfer Server ("node") and IBM Aspera High-Speed Endpoint environments. It complements other Aspera APIs and allows developers to seamlessly integrate with the Aspera ecosystem.

The Node API is a web service that runs on the server and enables you to synchronously do the following:

  • Manage user access to the node's file system and transfer capabilities.
  • Upload and download files and directories from the node using the FASP protocol or HTTP/HTTPS.
  • Manage transfers and files (start, stop, resume, and reconfigure transfers; create, delete, and rename files).
  • Retrieve information about the node, including available space, transfer events, and transfer volume.

Requirements

  • IBM Aspera High-Speed Transfer Server or IBM Aspera High-Speed Endpoint version 3.6.0 or later installed with a valid license.
  • In order to transfer with the node, the node's hosts file must contain an entry 127.0.0.1 localhost. The hosts file can be found in /etc/hosts on UNIX-like nodes.
  • Configure the node for HTTP Basic Authentication by creating a node username and password. See Node API Authentication and Authorization for instructions.

Access Control

The Node API accepts HTTP Basic Authentication and, for applications that directly access multi-tenant nodes, bearer tokens. Transfers that are started with the Node API require additional authentication. For more information about access control and transfer authorization, see "Node API Authentication and Authorization".

Bearer token authentication can be used for the following Node API endpoints: /events, /files, /permissions, /streams, /ops/transfers, and /usage.

Requests and Responses

The Node API uses standard HTTP methods, including GET, PUT, and POST requests, among others. Request bodies must be in JSON. Successful requests return an HTTP status code of 200 (in some cases, 201 or 204). If all or part of a request errors, the server returns a formatted JSON error message that contains the error code and a detailed explanation of the error. For example:

{
"error" : { "code" : 404, 
  "reason" : "Not Found", 
  "user_message" : "Transfer activity logging disabled" 
 }
}

Unusual and known errors may cause the Node API to respond with an empty JSON object. Therefore, Aspera recommends that you check the returned JSON for the error field or for an empty object.

Typical Workflow

The Node API can be used by web applications to:

  1. Confirm that the node is responsive (with /ping).
  2. Retrieve node configuration information (with /info). The node configuration is important because it might require that requests contain specific value-key pairs.
  3. Manage user access by creating access keys (with /access_keys) and, if the user authenticates with a bearer token, permissions on content (with /permissions).
  4. Browse and manage the file system (with /files/30/files). Manage filelocks on files (with /files/30/filelock).
  5. Transfer content between nodes (with /ops/transfers or, for streaming data, /streams).
  6. Monitor:

File Management Methods

The Node API offers two types of endpoints for file management.

  1. The /files/30 group.
    This group includes:
    • /files/30
    • /files/30/files
    • /files/30/filelock

    These endpoints:
    • allow you to manage files and filelocks by file ID
    • support bearer token authentication

  2. The /files/* group.
    This group includes:
    These endpoints:
    • allow you to manage files and filelocks by file path
    • do not support bearer token authentication, only Node API credentials or access keys. They cannot be used to integrate with Aspera Files.

SOAP Services

Developers who are experienced with the Aspera SOAP APIs can leverage them within their applications by adding the HTTP authentication and SSL security provided in the Node API. The Node API acts as a proxy to the Aspera SOAP web services provider, and all returned responses are in XML format.

More information on using SOAP can be found in the SOAP Web Services section. 

Client Setup

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, set up transfers, and operate the transfers through the Connect plugin. This setup allows you to offer your users a simple, branded user experience while utilizing Aspera technologies.

For information on how to set up your Connect Server, create a Node user, create a web service, and develop a frontend for your users, see Building a Simple Web Application.

 


Overview

The Node API can be used to ping and query information from Aspera Nodes as well as performing various system and file operations on the Node. The Node API provides secure access to a wide range of actions and is RESTful, which means that HTTP requests are used to interact with resources within a targeted Aspera Node.  In case SOAP services are needed the Node API offers an XML-based messaging through a SOAP service interface.

Requests and Responses

The Node API supports basic authentication, as defined by standard RFC 1945; in which the calling application authenticates itself using a Base64 encoded username and password. The Node API supports GET and POST requests; GET is the recommended method to retrieve information from a resource and POST is recommended for updating or modifying an entity.  If the Node API responds to a request with a HTTP status code of 200 the request was successful.  If Errors are found when handling the requests the server returns a formatted JSON error message that contains the error code and a detailed explanation of the error.  For example, an error might be returned in the following format.

 

Developers should note that some odd or known errors may occur and the Node API may respond with an empty JSON object. Therefore it is recommended to check the returned JSON for the error field or for an empty object.  As well as general errors, the server may also respond with normal HTTP status codes.  For example, 401 could indicate that the request is not authorized or a 404 could indicate that the path is invalid.

Responses are always in JSON format unless you are using SOAP, in which case the response will be in XML format.  For example, a returned XML format for a SOAP operation would be returned in the following format.

 

Transfer Workflow

The Node API offers two operations for preparing a download or upload operation. "/files/upload_setup" and "/files/download_setup" obtain a valid authorization token and reconcile user-defined transfer settings with the server-side settings.  These operations are beneficial as they:

  • Allow the developer not to worry about setting up a separate web application for the generation of authorization tokens, since the Node API provides it within an intuitive workflow,
  • Detect bad specs at load instead of when the user attempts a transfer, allowing the developer to handler errors before the user attempts a transfer,
  • Ensure the returned specs uses optimal settings for the targeted Aspera Node

Token Generation

Token-based authorization is the mechanism by which a transfer from an Aspera Node is controlled and authorized using a token.  Token generation can be done using the executable astokengen (astokengen.exe in Windows).  Transfers using token-based authorization require a token to be generated as the first step in the transfer process.  The Node API allows developers to prepare their transfers and generate a token via a simple REST request to an Aspera Node.  This operation is achieved by first submitting a transfer request.  If the request is proper a transferSpec JSON object will be returned that can be directly used in the application.

Transfer Setup

Examples of requests and their normal returned object can be found on the Example Requests page.  The normal workflow can be seen in the illustration below.  In this simple use case a page offers the user the ability to choose content and click a download button to initiate the download.  In this example there are a few Node API requests that take place.  When the page loads it makes three Node API requests, a /ping to verify that the server is alive,  a /file/info to get the information on the file system, and finally a /file/browse to get the content to display on the page.  After the user browses through the content and clicks the Download button an event is triggered.  This event performs the /files/download_setup request to generate an authorization token and builds the transferSpec needed to initiate the Connect transfer.

SOAP Services

Developers who are experienced with Aspera SOAP API can leverage them within their applications by adding the HTTP authentication and SSL security provided in the Node API.  The Node API acts as a proxy to the Aspera SOAP web services provider and all returned responses are in XML format.

More information on using SOAP can be found in the SOAP Web Services section. 

 


Getting Started

Getting Started

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 10.20.102.199):

<server>   <server_name>10.20.102.199</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 http://10.20.102.199:9091/pingcurl -k -i -X GET https://10.20.102.199:9092/ping

 


Creating 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 https://10.20.102.199:9092/infocurl -u testnodeuser:testpasswd -k https://10.20.102.199:9092/files/browse -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>

 


Creating a Web Service

In this section you will create a web application in Java that will expose 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 your needs you can easily add more methods to your server, for other methods and instructions on them please see the REST endpoints of the Node API.

To begin create a new project in your preferred IDE.  For this example, we are going to create a project called AsNodeAPIServiceProject.  Once you have your project open create a new Class called AsNodeAPIService, this class will contain the main method. In this class you are going to define two resources, AsNodeBrowseResource that has path /node/browse and AsNodeDownloadSetupResource that has path /node/setupdownload 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 resource you just defined will simply accept the HTTP request, retrieve the parameters received and finally make a REST request to the Node API using the Apache HTTPClient and send back the JSON result to the requester. Since the functionality of the two resources are similar, you can abstract it into a class called AbstractNodeAPIResource or code each one separately.

 

By using this layer of abstraction you can simply implement your AsNodeBrowseResource as the following:

 

Your AsNodeDownloadSetupResource would simply be:

 

Now that you have coded the two endpoints that we are using for this example we can compile and run the code.  You can either run it directly in your IDE or generate the HAR file and launch the service using 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#If using Windows: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

 


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

 

 


System Operations

System Operations

This section covers the different endpoints available through the Node API that deal with system operations. These operations are shared between Gen 3 and Gen 4 Nodes; however, when using Gen 4 Nodes you can use Gen 4 supported auehtentication methods.

 


Ping

A Ping allows you to see if the Node is running properly.  Ping is done by sending a HTTP GET request with an empty body and no authentication.  If the Node is available a HTTP response with code 200 is returned and an empty response body is returned.  However, if the response contains a JSON Object it will define the error that was encountered.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/info
Authentication: User
Response Format: JSON
Type: Synchronous
Minimum Version: 3

Curl Example

You can use curl to perform the request and read the return, be sure to change the address and port to the one your server uses.

curl -k -i -X GET https://10.20.102.199:9092/ping

 Response

Valid Node

HTTP/1.1 200 OK

Error (License Issue)

 

 


System Information

The System Information endpoint allows you to get system information on the Node.  The request contains user-based authentication, if the request is successful a HTTP response with code 200 is returned with a JSON Object containing basic information on the system.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/info
Authentication: User
Response Format: JSON
Type: Synchronous
Minimum Version: 3

Curl Example

You can use curl to perform the request and read the return, be sure to change the address and port to the one your server uses.

curl -k -i -X GET https://nodeuser2:aspera@10.20.102.199:9092/info

Response

 

 


File System Operations

File System Operations

This section covers the different endpoints available through the Node API that deal with file system operations. All operations respond with HTTP code 200.  Application level errors are noted in the JSON response.  You must check for the presence of the error field of the JSON object, which will indicate if the request failed and provide some insight into the problem.

An example of all Node Operations can be seen here

 


Paths Information

The Paths Information endpoint accepts an array of paths to query against the Node in a JSON format and requires authentication.  The HTTP response contains information on the requested paths and any path that is not valid will return an error.

Specifications

URL: http(s)://<node_server>:<node_port>/files/info
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Requests Parameters

{ "paths" : [ {"path" : "/mypath" }, {"path", "anotherPath"} ]}
paths array of paths
path the path name to query

Curl Example

You can use curl to perform the request and read the return, be sure to change the address, port, and user account to the one your server uses.

curl -k -i -X POST -d '{"paths":[{"path":"/"}, {"path":"browse.json"}, {"path":"not_existing_foo"}]}' https://nodeuser2:aspera@10.20.102.199:9092/files/info

Response

 

Response Parameters

paths array of paths
path the path name to query
basename the base name of the path
type the type of the path: file or directory
size the size of the path
mtime the last modification time of the path

 


Available Space

The Available Space endpoint is used to get information about the available space for the filesystem, drives or partitions (logical or physical) that contain the queried paths.  The endpoint requires user-based authentication and the request body contains the paths that should be queried in JSON format. If successful the Node responds with HTTP code 200 and a response containing space usage information or errors if present.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/space
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Requests Parameters

{ "paths" : [ {"path" : "/mypath" } ]}
paths array of paths
path the path name to query

Curl Example

You can use curl to perform the request and read the return, be sure to change the address and port to the one your server uses.

curl -k -i -X POST -d '{ "paths" : [ {"path" : "/mypath" } ]}' https://nodeuser2:aspera@10.20.102.199:9092/space

Response

 

Response Parameters

paths array of paths
path the path name to query
bytes_total the total space in bytes of the mount point of the path
bytes_free the free space in bytes of the mount point of the path
percent_free the percentage of free space of the mount point of the path

 


Browse File System

The Browse File System endpoint is used to browse a directory in the user's document root as defined in Node.  The request requires user-based authentication and the request body contains the path to browse in JSON format. The request can also include optional fields to filter the desired return data.  If successful a HTTP code of 200 is returned with content that matched the filters, if any.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/browse
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Request Parameters

path Absolute path to file or directory.
skip Skip the first "skip" results. Default 0
count Return at most "count" results.  It is client’s responsibility to keep track of number of results returned. Default 100.
sort Result sorting policy. Default none. Possible values are:
  • type (directory/file)
  • size_a (bytes, ascending)
  • size_d (bytes, descending)
  • mtime_a (modification date, ascending)
  • mtime_d (modification date, descending)
filters Filter out some paths during the browsing.
filters types Apply filter to content type (file, directory, others)
Valid type literals include:
  • "file"
  • "directory"
  • "symbolic link". {"filters" : {"types":["file","directory"]}}
filters names Apply filters to path names.
filters basenames Apply filters to basename only, not the entire path name.
filters size_min Include files >= to size_min (in bytes) NOTE: automatically restricts the results to files domain only
filters size_max Include files <= to size_max (in bytes) NOTE: automatically restricts the results to files domain only
filters mtime_min Include files updated >= mtime_min, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
filters mtime_max Include files updated <= mtime_max, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.

Example Request

Request Body:

 

Curl Request: For a curl request; be sure to change the address and port to the one your server uses.

curl -i -X POST https://nodeuser2:aspera@10.20.102.199:9092/files/browse -d '{"path":"/","sort":"size_d","filters":{"mtime_min":"2012-03-15 15:09:00","size_max":1000}}'  curl -i -X POST https://nodeuser2:aspera@10.20.102.199:9092/files/browse -d '{"path":"/","sort":"size_d","filters":{"mtime_min":"2012-03-15 15:09:00","types":["file","directory"],"size_max":1000}}'

Response Attributes

path path returned by the browse operation
base name base name of the path
type type of the path (file, directory, ...)
size the size
mtime last modification time, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
item_count the number of returned items
total_count the number of found items
parameters element opening the operation parameters
path the path to browse
skip the number of items to skip in the result
count the maximum number of items to return in the response

Response Example

 

 


Create Files and Directories

The Create Files and Directories endpoint is used to create a file or directory in the user's document root as defined in Node. The request requires user-based authentication and a body containing the paths of the file or directory to create in a JSON format. The response body contains the created paths.  If an error is present in the response body the creation operation failed for that path.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/create
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Requests Parameters

{ "paths" : [{ "path" : "path/to/dir1", "type" : "directory" }, { "path" : "path/to/dir2", "type" : "directory" }, { "path" : "path/to/file", "type" : "file", "contents":"base64-encoded data" }]}
path Path to file or directory, relative to the document root path.
type 'file' or 'directory'
contents this field is used for file creation.  It holds base64 encoded data for file creation (this file has a max size of 1MB)

Request Example

 

Response Example

 

 


Delete File or Directory

The Delete File or Directory endpoint deletes the specified paths in the request body.  This operation requires user-based authentication.  A response of the paths deleted is returned or any errors and their respected path are also returned.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/delete
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Requests Parameters

paths array of paths to delete
path the path to delete

Curl Example

You can use curl to perform the request and read the return, be sure to change the address and port to the one your server uses.

curl -k -i -X POST -d '{"paths" : [ { "path" : "/full/path/to/dir3" }, { "path" : "/full/path/to/dir2" }]}'  https://nodeuser2:aspera@10.20.102.199:9092/files/delete

Response

 

Response Parameters

paths array of paths
path full path to delete
error Presence indicates the path could not be deleted (code, reason and user_message). eg. "error" : {
"code" : 404, "reason" : "Not Found", "user_message" : "The system cannot find the file specified."
}

 


Search File System

The Search File System endpoint allows the user to search using certain conditions and terms in a specified path.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/search
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Requests Parameters

path Absolute path to file or directory.
skip Skip the first "skip" results. Default 0
count Return at most "count" results.  It is client’s responsibility to keep track of number of results returned. Default 100.
sort Result sorting policy. Default none. Possible values are:
  • type (directory/file)
  • size_a (bytes, ascending)
  • size_d (bytes, descending)
  • mtime_a (modification date, ascending)
  • mtime_d (modification date, descending)
filters Filter out some paths during the browsing.
filters types Apply filter to content type (file, directory, others)
Valid type literals include:
  • "file"
  • "directory"
  • "symbolic link". {"filters" : {"types":["file","directory"]}}
filters names Apply filters to path names.
filters basenames Apply filters to basename only, not the entire path name.
filters size_min Include files >= to size_min (in bytes) NOTE: automatically restricts the results to files domain only
filters size_max Include files <= to size_max (in bytes) NOTE: automatically restricts the results to files domain only
filters mtime_min Include files updated >= mtime_min, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
filters mtime_max Include files updated <= mtime_max, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.

Curl Example

You can use curl to perform the request and read the return, be sure to change the address and port to the one your server uses.

 

Response

 

Response Parameters

path path returned by the browse operation
base name base name of the path
type type of the path (file, directory, ...)
size the size
mtime last modification time, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
item_count the number of returned items
total_count the number of found items
parameters element opening the operation parameters
path the path to browse
skip the number of items to skip in the result
count the maximum number of items to return in the response

 


Rename Files and Directories

The Rename Files and Directories endpoint allows you to rename files and directories specified by the path specified in the JSON request body.  A response body contains the paths to the renamed files or any errors and their path.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/rename
Authentication: User
Response Format: JSON
Type: Synchronous
Request Parameter: JSON
Minimum Version: 3

Request Example

 

Requests Parameters

{"paths" : [{ "path" : "/full/path/to", "source" : "dir1", "destination" : "new_dir1" }]}
paths array of paths
path full path of directory where is the file or directory to rename
source the current name (relative to its parent) of directory or file to rename
destination the expected new name (relative to the same parent) of directory or file

Response Example

 

Response Parameters

{"paths" : [{ "path" : "/full/path/to", "source" : "dir1", "destination" : "new_dir1" }]}
paths array of paths
path full path of directory where is the file or directory to rename
source the current name (relative to its parent) of directory or file to rename
destination the expected new name (relative to the same parent) of directory or file
error Presence indicates the path could not be renamed (code, reason and user_message). eg. "error" : {
"code" : 409, "reason" : "Conflict", "user_message" : "Destination exists already"
}

 


Transfer Operations

Transfer Operations

This section covers the different endpoints available through the Node API that deal with setting up transfers. The principle of the transfer setup API is to allow third party application (other than the client and server involved in the transfer) to provide the client all the transfer information and authorization necessary to initiate a transfer.

The transfer spec returned by the Node contains sufficient information to start a transfer without surpassing any restrictions set in the request as well as those imposed by aspera.conf or third party applications. If there is any conflict between the transfer request and the aspera.conf, default initial values are reconciled. Third-party applications can be an Aspera applications or a custom applications.

 


Upload Setup

The Upload Setup endpoint allows you to get the information needed for an upload.  The request provides a JSON Object called the transfer_request and the response from the Node includes the transfer_spec JSON Object that includes the needed information for uploads.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/upload_setup
Authentication: User
Response Format: JSON (transfer_specs)
Type: Synchronous
Request Parameter: JSON (transfer_requests)
Requirements: Token Generation Must be Setup

Curl Example

curl -i -v -X POST -u testnodeuser:testpassword -d '{ "transfer_requests" : [ { "transfer_request" : { "paths" : [{}], "destination_root" : "/" } } ] }";' http://devdemo.asperasoft.com:9091/files/upload_setup

Response

 

Transfer Requests

  • transfer_request
  • source_root, destination_root, and paths (paths consist of sources and/or destinations).
    • A download request requires at least one source
    • An upload request requires at least one destination. 
    • The source or destination may be "." to signify downloading or uploading the source_root or destination_root itself.
  • content_protection
  • target_rate_kbps
  • target_rate_cap_kbps
  • rate_policy and rate_policy_allowed ("low | fair | high | fixed")
  • cipher and cipher_allowed ("none | aes-128")
  • remote_host
  • ssh_port (integer)
  • fasp_port (integer)
  • http_fallback (true|false)
  • cookie (way to include metadata with transfer. Node will echo back the cookie)
  • tags. (way to include metadata with transfer. Node may add or modify tags)
  • token_life_seconds to specify the validity lifetime of the generated token (available since Enterprise Server 3.6.3)

Transfer Specifications

To learn more about transfer_spec please see the Transfer Specifications page in Connect Client.

 


Download Setup

The Download Setup endpoint allows the developer to get the information needed for a download.  The request provides a JSON Object called the transfer_request and the response from the Node includes the transfer_spec JSON Object that includes the needed information for downloads.

Specifications

URL: http(s)://<node_user>:<node_user_passwd>@<node_server>:<node_port>/files/download_setup
Authentication: User
Response Format: JSON (transfer_specs)
Type: Synchronous
Request Parameter: JSON (transfer_requests)
Requirements: Token Generation Must be Setup

Curl Example

curl --insecure -i -H "Content-Type: application/json" -X POST https://testnodeuser:testpassword@devdemo.asperasoft.com:9092/files/download_setup -d "{ \"transfer_requests\" : [ { \"transfer_request\" : { \"paths\" : [ { \"source\" : \"100MB\" } ] } } ] }"

Response

 

Transfer Requests

  • transfer_request
  • source_root, destination_root, and paths (paths consist of sources and/or destinations).
    • A download request requires at least one source
    • An upload request requires at least one destination. 
    • The source or destination may be "." to signify downloading or uploading the source_root or destination_root itself.
  • content_protection
  • target_rate_kbps
  • target_rate_cap_kbps
  • rate_policy and rate_policy_allowed ("low | fair | high | fixed")
  • cipher and cipher_allowed ("none | aes-128")
  • remote_host
  • ssh_port (integer)
  • fasp_port (integer)
  • http_fallback (true|false)
  • cookie (way to include metadata with transfer. Node will echo back the cookie)
  • tags. (way to include metadata with transfer. Node may add or modify tags)
  • token_life_seconds to specify the validity lifetime of the generated token (available since Enterprise Server 3.6.3)

Transfer Specifications

To learn more about transfer_spec please see the Transfer Specifications page in Connect Client.

 


Version 2

Version 2

Version 2 supports all of the features of Node Version 1 with the addition of a few extra endpoints that can be used.  These endpoints are explained below.  Version 2 is derived from the Shares API and operations are handled synchronously within the response/request cycle.  

List Node to Node Transfers (/transfers)

To list Node to Node transfers you can simply send a GET request to the /transfers endpoint.  This will return a list of Node to Node Transfers in JSON format.  An example of a returned list can be seen below.

 

Create Node to Node Transfer (/transfers)

To create a Node to Node transfer you need to send a transfer JSON object with the parameters to the /transfers endpoint.  After the transfer has been created you will get a response containing the transfer object; please note that paths are omitted in the transfer object. When using Node to Node transfers you need to ensure that persistent storage is enabled. This can be done by simply using asconfigurator (which is normally found in the /bin directory of your Aspera Server installation) or editing the aspera.conf file directly. To enable this using asconfigurator you can run the following command:

asconfigurator -x “set_central_server_data;persistent_store,enable"

After editing the aspera.conf file or using asconfigurator you will need to restart asperacentral and asperanoded in that order for the changes to take affect.

You will also need to ensure that the Aspera public key is present in authorized_keys file in the user’s .ssh directory. If that file is not present you can create it and ensure the proper permissions based on your system. The needed content for that file can be found in the aspera_id_dsa.pub file which is normally in the main aspera user’s var folder.

For example, if you could run the following cURL command targeting the /transfers endpoint to create a new Node to Node transfer:

curl -v --insecure -u [username]:[password] -X POST -d '{ "transfer": {"remote_host": “[server]”, "ssh_port": 33001,"remote_user": “user_name", "direction": "send","source_root": "/", "destination_root": "/Upload", "paths": [ { "source": "testFile", "destination": "testFile"} ], "rate_policy" : "fair" } }'  [server:port]/transfers 

That command will return something similar to what is seen below:

 

Below is an example of possible values that can be returned. It should be noted that not all of these values will be returned.

 

Get Transfer Object (/transfers/60)

If you wanted to get the status of the transfer you can simply send a GET request to the /transfers/60 endpoint which would return the details for that transfer (excluding the paths). This is a great way to get details about the transfer right after it is submitted, however, for getting information on the transfer for an extended period of a time (more than about three minutes from the time it is submitted) you should use the Reliable Query API with a filter using a cookie instead of the job ID, this will ensure that you can continuously monitor the transfer. For example, the cURL command below will query using cookie called "smart-xfer-cookie":

curl -k -i --basic -u "[user]:[password]" -H "Content-Type: text/xml;charset=UTF-8" -H "SOAPAction:FASPSessionNET-200911#GetSessionInfo" -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:typ=\"urn:Aspera:XML:FASPSessionNET:2009/11:Types\"><soapenv:Header></soapenv:Header><soapenv:Body><typ:GetSessionInfoRequest><SessionFilter><Cookie>smart-xfer-cookie</Cookie></SessionFilter></typ:GetSessionInfoRequest></soapenv:Body></soapenv:Envelope>" -X POST "https://[server]:9092/services/soap/Transfer-201210"

The XML used in the cURL command above is seen formatted below:

 

Edit Existing Transfer (/transfers/60)

To edit an existing transfer you can send a JSON formatted request to the /transfers/{ID} endpoint.  You can only alter one transfer object property per request. This will return the transfer object of the ID specified; please note that paths are omitted in the transfer object.  Properties that you can alter include:

  • rate_policy
  • target_rate_kbps
  • min_rate_kbps
  • target_rate_cap_kbps
  • lock_rate_policy
  • lock_target_rate
  • lock_min_rate
  • status

For example, if you wanted to resume or stop a transfer you could send the following request:

 

Delete Existing Transfer (/transfers/60)

To delete an existing transfer you can send a DELETE request to the /transfers/{ID} endpoint.  This will delete the transfer and respond with an HTTP status code of 204 (No Content).

Locale Information (/locals)

You can get the supported locale names and codes by simply sending a GET request to the /locales endpoint.  This will respond with a JSON object containing the supported locales, for example:

 

 


Live Demo

Live Demo

Below are the API documentation with live demo of the Node API.

 


Example Requests

Download Examples

Here you can find examples of some common requests and responses using different transfer_requests for downloads.

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

 


Upload Examples

Here you can find examples of some common requests and responses using different transfer_requests for uploads.

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

Request

 l;

Response

 l;

 


Sample Code

Node+Connect Sample

Node and Connect allows you to offer file operations to your clients through a web application.  A server is used to communicate between the client and the Node server.  This server simply receives a request from the client (using POST data) and returns the JSON from the Node server for the client to process.  

This document covers two possible setups.  The first setup assumes you have a web server and will simply host a normal web application on that server that will communicate with your client-side JavaScript.  The second setup gives you the ability to create a single application that provides all aspects of the system (client side GUI, server side logic, and web server).  Both use the same general concept for communicating and loading the page, however, the single application includes extra code for handling the server side operations and rendering the HTML.  You can simply switch between types in the server side section below.  It should also be noted that if you use the all-in-one approach you will not need to use the Client Side setup section below since the frontend is implemented in the server side code.

With the first setup (web application) all of the HTML is handled client side and the server is only receiving requests and returning the Node JSON to the client.  Essentially:

  1. Client initiates session (visits webpage)
  2. JavaScript sends POST data to server side web application
  3. Server side web application requests data from Node
  4. Server side web application sends Node data back to JavaScript
  5. JavaScript parses data accordingly
  6. JavaScript changes the HTML accordingly

The example below shows how to implement either a PHP, .NET (C#), Java or Ruby version of this server side web application.  In this example the server side code is very minimalistic since the bulk of the work is handled in JavaScript.  The server is mainly for authorizing against Node, you could think of it as a 'middle-man' between Node and JavaScript.  This example uses AJAX to get the data and perform operations without needing to reload the page and uses jQuery for targeting elements and creating a clean, user friendly interface.

With this approach we can offer the ability to download multiple files by clicking each file or the "Download All" button under the cog (simultaneous downloads), as well as uploading multiple files.  When download/uploads take place the area behind them turns into their progress bars to provide a clean, minimalistic design.

For the web application the JavaScript code remains the same regardless of the server side language.  To implement this example on your own machine you simply need to copy the code for your preferred server language and change the global variables. JavaScript handles most of the work including parsing the JSON using JSON.parse() which is supported in all modern browsers and includes support for Internet Explorer 8+ and Firefox 3.5+.  If you need to support earlier versions we recommend using jQuery.parseJSON() which can be found in jQuery 1.4.1+, which supports Internet Explorer 6+.

Getting Started

 Download Full Example

To get this example working you first need to decide what type of web server you are going to use or what type of server you currently use.  We offer a simple to implement server side web application that works by simply changing the variables to match your Node setup.  However, you are free to customize it further to meet your needs or business logic.  Since the bulk of the work is done client side can simply use any web server to host your JavaScript and HTML/CSS or reference the JavaScript in your Content Management System.

This example offers the ability to:

  • List Files (browse)
  • Download (download_setup)
  • Upload (upload_setup)
  • Delete File/Directory (delete)
  • Create Directory (create)
  • Rename File/Directory (rename)

You can include additional operations as needed or remove operations that are not needed.

Files Needed

If you download the example above you will receive all of the files listed on this page.  There are also a few third party libraries being referenced using their CDNs (for a production environment we recommend downloading these and hosting them on your own server [except for the Aspera Libraries]).  Below is a list of the third party libraries being used from CDNs.

  • jquery.min.js (JavaScript) - jQuery v1.11.2 (Required)
  • connect/*.js (JavaScript) - Aspera libraries for Connect (Required)
  • bootstrap.min.js/css (JavaScript and CSS) - Bootstrap core (Optional)

Server Side Setup

Depending on your needs you can either use a full server approach or a regular web application. The full server approach is a single application that serves as its own web server and the one application provides everything for delivering the site. The HTML, JavaScript and CSS are embedded in the application code and this does not require the server being used to have any web server service (IIS or Apache) running. If you choose the regular web application you can simply run the server side web application like any other web application in your environment (this does not provide any HTML, JavaScript or CSS and needs the code found in the Client Site Setup Section.

Once you know what type of web server you are going to use you need to simply copy and paste the code below for your setup into your web server and compile it (if needed).  Simply choose your language below to get the code.  Remember to change the global variables to match your Node setup.  Since some languages require you to run on a different port or your setup may have your server side web application on a different domain you need to consider CORS (Cross Origin Resource Sharing).  As part of the server side web application a "Access-Control-Allow-Origin" header is returned stating what domains can pull resources from this server.  In the example we have it setup to "*" which means any, however, for security you should change this to the list of specific domains that are allowed to pull resources from your server side web application.

To begin, choose your preferred language and then choose whether you want the full server application (self serving, all-in-one application) or just the Web Application (basic web application for talking to Node and JavaScript).

Requirements

  • In addition to a normal PHP 5 Server you need the php-curl extension
    • If using a WAMP bundle php-curl was already installed
    • In Linux install php5-curl using your preferred package manager
    • Remember to restart your web server service after installing php-curl

Definitions

The following are definitions of parameters found near the top of the file in the PHP, Ruby, Java, and C# code examples. Replace the example values in the file with the corresponding values from your working Aspera Client configuration.

Parameter Definition Replace With
NODE_SERVER_AND_PORT Hostname Server name
NODE_SERVER_USER Node server ID Client ID
NODE_SERVER_PASS Password for the node server Secret

 

 

Requirements

  • In addition to a normal PHP 5 Server you need the php-curl extension
    • If using a WAMP bundle php-curl was already installed
    • In Linux install php5-curl using your preferred package manager
    • Remember to restart your web server service after installing php-curl

 

 

Requirements

  • In addition to a normal Ruby install, you need the following gems
    • Sinatra (sudo gem install sinatra)
    • JSON/Pure (sudo gem install json_pure)
 

Requirements

  • In addition to a normal Ruby install, you need the following gems
    • Sinatra (sudo gem install sinatra)
    • JSON/Pure (sudo gem install json_pure
 

Requirements

To use this you will need to simply create an ASPX single file page and host it on a Windows machine with IIS. For more information on setting up IIS in Windows please see the IIS Installation Guide.

 

Requirements

This C# program does not use any third party dependencies and instead uses the HttpListener Class. This class can run on any Windows machine since Windows Server 2003 or Windows XP Service Pack 2. To use this program simply compile the Command Line application and run it as an Administrator in Command Prompt. To stop the program type STOP in the command prompt.

 

Requirements

This Java Servlet can be ran as a regular Servlet in any Java web server (like Tomcat or Glassfish). It can also be converted into a JSP file if you would prefer to use a JSP file instead of a Servlet.

 

Requirements

This Java Server application runs as a standalone Java application. Simply compile it (javac -g [name].java) and run it on your server (java [name]). When started it will simply state what port (defined in the code) it is using and you can then go to the page in any web browser by going to [serveraddress]:[port].

 

Client Side Setup

Most likely you will use the same web server to host your server side web application as you do for the client side files.  However, you can use any server for the server side web application and any server for your client side website; you can also use any CMS or markup.

The client side example is made up of three parts, the JavaScript, HTML markup, and CSS.  The CSS in the example is not important as it is just for the style of the page and you will use your own CSS in your product.  The HTML markup is also not that important and as long as you can easily target a few items with jQuery you can design it any way.  For example, we use a table for listing the files, however, you could use an unordered list or any other structure that allows you to iterate its content (including custom divs).

The example below uses Bootstrap for its design, however, this is not required and pure HTML or any framework can be used.  We have also includes some extra functions for creating a more 'user friendly' experience; like cleanSize and cleanDate which takes the raw information and turns it into a more friendly format (if you wish to use this in your code you may need to alter the output to match your locale. This example uses US English), we have also includes functions that allow you to sort by columns as well as search the content of the current directory; these are optional and can be removed if not desired.

To understand what the JavaScript does we have includes detailed comments above each function that explains its purpose.  We recommend reading over these functions to understand their purpose.  However, if you plan to use the code as is you should remove the comments before releasing to a live environment or minifying the file to help with performance.

To view the source for the JavaScript or HTML click the tabs below.  We have also includes a tab that contains the CSS, however, this has no affect on the use of the example it is just styling and is provided for copy and pasting purposes only.  It is important to note that the HTML is relatively basic and there are only a few areas that hold data from the JavaScript and must have proper IDs that match the JavaScript code.  Please see the comments in the HTML for more information.

 
 
 

 

 


Utilities

cURL Test

You can use this online cURL tester to test methods against your server. This test will allow you to test all of the Node Endpoints that are available. You can use your own server or you can use the Aspera Demo Server.

Test with an Aspera Server

Powered by ChronoForms - ChronoEngine.com

 

 


transferSpec Test

You can use this section to test your own transferSpec. Simply copy and paste your transferSpec and connectSpec into the text box below. When ready hit Test transferSpec. This will initiate the Download or Upload. It is recommended to have Allow Connect Dialogs set to YES, since you will be unable to see the Connect Client window if it is set to NO. You can paste both transferSpec and connect Spec if passing in JavaScript code. If you are passing JSON be sure to include it just as it would be returned to you from the server. When using JavaScript be sure to declare transferSpec properly.

 Using Token

Test transferSpec

 


Special Cases

Using Node API with Azure

This guide will show you how to use Connect and the Aspera Node API with Azure Storage and Aspera Server on Demand for Azure.  This guide assumes you already have a Windows Azure account and have access to create storage accounts and purchase add-ons from the Azure Store. For a full Azure example with Connect please see the Azure Connect Sample.

Setup an Azure Storage Account

  1. From the Azure Management Portal select the "STORAGE" link on the left hand side of the navigation pane
  2. Click the "New (+)" link at the bottom of the page. 
  3. Click "Quick Create" and give the storage account a name and choose a region.
  4. Once the storage account has been created you can select it within the management portal. With your storage account selected, click "Manage Keys" at the bottom of the page. A dialog will come up showing you 2 important pieces of information that you should note:
    • AZURE_STORAGE_ACCOUNT_NAME: The name you gave the Storage account
    • AZURE_STORAGE_PRIMARY_ACCESS_KEY: A long string
  5. Close the Access Key Management dialog, select your newly-created storage from the list and click on "CONTAINERS" in the upper-middle of the screen.  Click on "New" again in the lower left, and name a BLOB container for your storage.

Purchase the Aspera on Demand Add-On From the Azure Store

  1. From the Azure Management Portal select the "ADD-ONS" link on the left hand side of the navigation pane 
  2. Click the "New (+)" button at the bottom of the page
  3. Select the "STORE" link on the left hand side of the page
  4. Select "Aspera on Demand"  from the list of add-ons
  5. Click the "next" arrow, give the service a name and complete the purchase of the Aspera on Demand Service.  Once the Aspera on Demand service is purchased it will show up in your list of purchased ad-ons.
  6. Select the service you just created from the list of purchased services and then click the "MANAGE" link at the bottom of the page.
  7. You will be at a page that allows you to create one or more sets of credentials. Click the "New User Credential" button. Give the new credential set a description and select your desired availability zone from the drop-down list. You will be presented with 4 important pieces of information that you need to note:
    • ASPERA_ON_DEMAND_HOST_NAME: (Host) host name of the Aspera on Demand Server to use 
    • ASPERA_ON_DEMAND_USERNAME: (User) A long string
    • ASPERA_ON_DEMAND_PRIMARY_ACCESS_KEY:  (Password) a long string
    • AZURE_BLOB_CONTAINER:  (Container ID) a long string
  8. Click the Save button

Coding/Configuration for Using Azure Services with Aspera Connect

For demonstrations we use the Aspera-Node-Connect example below to illustrate this. There are just a few changes that need to be made for this example to work with Azure Services.

  1. Change the Node username to the ASPERA_ON_DEMAND_USERNAME you obtained from the Aspera On Demand add-on you purchased above
  2. Change the Node password to the ASPERA_ON_DEMAND_PRIMARY_ACCESS_KEY you obtained from the Aspera On Demand add-on you purchased above
  3. Change the Node Server Name to the ASPERA_ON_DEMAND_HOST_NAME you obtained from the Aspera On Demand add-on you purchased above
  4. Formulate an Azure storage account URL from the Azure Storage Account you created above. This URL has the following format:
    1. azu://AZURE_STORAGE_ACCOUNT_NAME:AZURE_STORAGE_PRIMARY_ACCESS_KEY@blob.core.windows.net /BLOB_CONTAINER
      • AZURE_STORAGE_ACCOUNT_NAME is replaced by the value of the Azure Storage Account Name retrieved above
      • AZURE_STORAGE_PRIMARY_ACCESS_KEY is replaced by the value of the Azure Storage Primary Access Key retrieved above (value below should be URL Encoded)
      • BLOB_CONTAINER is replaced by the value of the Azure Blob Container retrieved above
      • Note the Colon ":" between the AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_PRIMARY_ACCESS_KEY.
  5. In your code: set the destination_root in your Node API requests to the Azure URL from above
  6. For uploads, In your Aspera Connect transfer specification definition replace the destination_root with the Azure URL from above
  7. For downloads, In your Aspera Connect transfer specification definition replace the source_root with the Azure URL from above

Below is the Azure Service compatible Node-Connect Demo code with placeholders for the changes mentioned above

 Customize Code

 
 

Code Generation

To generate the code on this page to your needs, please fill out the fields below.

Powered by ChronoForms - ChronoEngine.com

×

 



Node API Documentation

API Documentation

To view the API documentation, please select the version you wish to view

 


Video player

Video

×