For reference information on Node API endpoints, see IBM API Explorer.

Node API Capabilities

The Node API is a REST API web service that runs on an Aspera server (node) and enables you to 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 (by HTTP fallback).
  • Initiate and control transfers and manage 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.

The Node API complements other Aspera APIs and allows developers to seamlessly integrate their applications with the Aspera ecosystem.

Aspera Nodes

Aspera nodes—Aspera servers that are configured to support the Node API—can include:

Node Type Description
Aspera on Cloud (AoC) Aspera’s cloud-based hosted service that enables content transfer and sharing across a hybrid-cloud infrastructure
Aspera on Cloud transfer service (AoCts) A feature of AoC that allows you to transfer to and from your own cloud storage through an Aspera-hosted transfer server cluster
Aspera Transfer Cluster Manager (ATCM) A self-managed cluster of Aspera nodes in the cloud
IBM Aspera High-Speed Transfer Servers (HST Server) Aspera’s enterprise transfer server software that can be deployed on-premises or in the cloud
IBM Aspera High-Speed Transfer Endpoint (HST Endpoint) An entry-level transfer endpoint that can connect to other HSTEs and nodes
Aspera on Demand (AOD) A pre-configured instance of HSTS that you can self-manage in your own cloud environment

HSTS and HSTE require configuration in order to support the Node API. For instructions, see Configuration for Node API

Access Control

The Node API accepts HTTP Basic Authentication and OAuth2 bearer tokens. In addition, when node-to-node transfers are started with the Node API (with a POST request to /ops/transfers), the request body may contain SSH authentication credentials to the remote node and an authorization token for access to the storage on the remote node. For more information about access control and transfer authorization, see Node API Security and Node-to-Node Transfer Authentication and Authorization.

Endpoint Support by Node Type

Some Node API endpoints support only HTTP Basic Authentication or only non-expandable storage. The following table shows the Node API endpoints that are supported on different types of Aspera nodes.

Endpoint AoC AoCts, ATCM HSTS, HSTE, AOD
/access_keys No Yes (once you have a master key, create sub-access keys) Yes
/events Yes Yes Yes
/files/{id}*

/files/{id}/files

/files/{id}/content

/files/{id}/filelock

Yes Yes Yes
/files/browse*

/files/create

/files/delete

/files/download_setup

/files/filelock

/files/rename

/files/search

/files/unfilelock

/files/upload_setup

No Yes Yes
/info No Yes Yes
/ops/transfers Yes Yes Yes
/permissions Yes Yes (permissions apply only to bearer token users) Yes (permissions apply only to bearer token users)
/ping No Yes Yes
/self Yes Yes Yes
/space No No Yes
/usage Yes Yes Yes

* For more information about these two groups of file system browse and management endpoints, see File Management Methods.

Requests and Responses

The Node API uses standard HTTP methods, including GET, PUT, and POST, among others. Request bodies must be in JSON.

Successful requests return an HTTP status code of 200 (in some cases, 201 or 204).

Error and Exception Handling

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" 
 }
}

HTTP error codes include:

  • 400 (bad request)
  • 404 (not found)
  • 409 (conflict)
  • 500 (internal server error)
  • 503 (service unavailable)

Note: Some errors (including known errors) can 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 when the HTTP status code indicates an error (all codes other than 2xx).

Typical Use Cases

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:
    • node events, such as transfer start, file creation, and changing permissions (with /events)
    • transfer progress (with /ops/transfers)
    • bandwidth usage (with /ops/transfers/bandwidth)
    • transfer volume (with /usage)
    • available space on the node (with /space) (Note: /space is not supported on nodes with expandable storage, such as AoC, AoCts, and ATCM)

For examples of how to work with the Node API, see Tutorials and Code Examples.

File Management Methods

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

  1. The /files/{id} group. The Aspera-recommended, next-generation file management endpoints.
    This group includes:
    • /files/{id}
    • /files/{id}/files
    • /files/{id}/filelock

    These endpoints:

    • allow you to manage files and filelocks by file ID
    • provide robust glob filtering for search and browse than /files/browse and /files/search
    • support bearer token authentication

  2. The /files/* group. An earlier version of Node API file management endpoints that are still supported.
    This group includes:
    • /files/browse
    • /files/create>
    • /files/delete
    • /files/rename
    • /files/search
    • /files/filelock and /files/unfilelock

    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 on Cloud.

    NOTE: Browsing and searching with /files/browse and /files/search can be very slow if the node is in cloud storage. Aspera strongly recommends using /files/{id}/files for cloud-based nodes.