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/{id}/files). Manage filelocks on files (with /files/{id}/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/{id} group.
    This group includes:
    • /files/{id}
    • /files/{id}/files
    • /files/{id}/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.

Video player

Video

×