Node API Examples


The Aspera Noded API is the primary REST API for interacting with an Aspera Server.  The API provides many functions, including file operations, transfer authorization, transfer initiation, and transfer status.  This Article provides some simple examples of how to query the API, using the curl command.

Note: There are more examples and explanations on the Aspera Developer Network

API Examples

File operations

These examples show how to list, delete, rename files via the Noded API.

1. List files

# curl -k -i -X POST -d ' { "path" : "/" }' https://USER:PASSWORD@HOST:9092/files/browse

2. Check for available space

# curl -k -i -X POST -d '{ "paths" : [ {"path" : "/" } ]}' https://USER:PASSWORD@HOST:9092/space

3. Delete a file

# curl -k -i -X POST -d '{ "paths" : [ {"path" : "/FILENAME" } ]}' https://USER:PASSWORD@HOST:9092/files/delete 

Transfer Authorization

These examples show how to authorize a transfer via the Noded API.

1. How to request an upload transfer authorization

curl -s -k -i -v -X POST -u USER:PASSWORD -d '{ "transfer_requests" : [ { "transfer_request" : { "paths" : [{}], "destination_root" : "/" } } ] }' https://HOST/files/upload_setup

2. How to request a download transfer authorization

curl -s -k -i -v -X POST -u USER:PASSWORD -d '{ "transfer_requests" : [ { "transfer_request" : { "paths" : [{}], "destination_root" : "/" } } ] }' https://HOST/files/download_setup

3. Azure: How to request authorization for an upload to Azure

Make sure you have your Azure storage account name and your storage primary access keys.

# curl -k -i --basic -u "USER:PASSWORD" -H "Content-Type: application/javascript" -H "Accept: application/javascript" -d '{"transfer_requests":[{"transfer_request": {"destination_root":"azu://", "paths":[]}}]}'-X POST

Transfer initiation

This example shows how to initiate a transfer via the Noded API.

# curl -k -i --basic -u "USER:PASSWORD" -H "Content-Type: application/javascript" -H "Accept: application/javascript" -X POST -d TRANSFER_AUTHORIZATION_JSON https://HOST:9092/ops/transfers

Transfer status

These examples show how get transfer status via Noded API.

1. List all transfers

# curl -kigs https://USER:PASSWORD@HOST:9092/ops/transfers

2. List details on specific transfer

# curl -kigs https://USER:PASSWORD@HOST:9092/ops/transfers/TRANSFER_ID
Note: Substitiute TRANSFER_ID with the actual transfer id (obtained from step 1 above)

Transfer status - advanced examples 

1. Returns only the ids for active transfers

curl -kigGs  -u USER:PASSWORD -d filter=id -d active_only=true https://HOST:9092/ops/transfers

2. Returns only the short summary for all active transfers

curl -kigGs  -u node_user:aspera -d filter=short_summary -d active_only=true https://localhost:9092/ops/transfers

3. Returns only the summary for all active transfers

curl -kigGs  -u node_user:aspera -d filter=summary -d active_only=true https://localhost:9092/ops/transfers

4. Returns only the long summary for all active transfers

curl -kigGs -u node_user:aspera -d filter=long_summary -d active_only=true https://localhost:9092/ops/transfers 

5. Once you have an id, you can perform a GET request on an individual transfer

curl -kigGs -u node_user:aspera https://localhost:9092/ops/transfers/2ec7ff1b-dd7d-4509-8959-f652df4a5a73

6. Returns the short summary for the first two transfers

curl -kigGs  -u node_user:aspera -d filter=short_summary -d count=2 https://localhost:9092/ops/transfers

7. Returns the fifth and sixth transfers

curl -kigGs  -u node_user:aspera -d filter=short_summary -d count=2 -d iteration_token=5 

8. Returns the third and fourth active transfers

curl -kigGs  -u node_user:aspera -d filter=short_summary -d count=2 -d iteration_token=3 -d 
active_only=true https://localhost:9092/ops/transfers

9. You can make custom JSON tags.  Every level of a JSON hash is delimited with a dot (.) in the query.  For instance, for a.b.c.d.e=2, the ascp transfer would look like this:

ascp -i ~/.ssh/id_rsa --tags='{"a": {"b": {"c": {"d": {"e":2 } } } } }' file.txt

You could query node for a.b.c.d.e=2 like this:

curl -kigGs -u node_user:aspera -d tag="a.b.c.d.e=aspera" https://localhost:9092/ops/transfers

10. All of these params can be used together.  For example to return only the ids for the eleventh through twentieth active transfers, with xfer_retry set to 10, you could issue the following request:

curl -kigGs -u node_user:aspera -d tag="a.b.c.d.e=aspera" -d active_only=true -d iteration_token=10 -d count=10
-d filter=id https://localhost:9092/ops/transfers

Transfer status - using tags

Noded API supports tags. If a transfer was initiated using a tag, then you can query using those tags.  For example if a transfer is initiated with tags as such:

ascp -i ~/.ssh/id_rsa --tags='{"aspera":{"xfer_id":"123","xfer_retry":10},"test":"aspera"}' file.txt

Any of these requests would return that transfer

curl -kigGs -u USER:PASSWORD -d tag=aspera.xfer_id=123 https://HOST:9092/ops/transfers
curl -kigGs -u USER:PASSWORD -d tag=aspera.xfer_retry=10 https://HOST:9092/ops/transfers
curl -kigGs -u USER:PASSWORD -d tag=test=aspera https://HOST:9092/ops/transfers

License status

Noded API supports the reporting of entitlement information.  For example if your noded user has sufficient credentials, you can see the status as follows:

curl -kigGs -u USER:PASSWORD https://HOST:9092/license
NOTE: to create a noded user with sufficient credentials, use the --internal switch, as follows:
/opt/aspera/bin/asnodedadmin -a -u USER -p PASSWORD --internal --acl-set internal
Powered by Zendesk