Overview

Console REST API

The Console REST APIs allow you to Submit, Control and Monitor Transfers. The Console API is available for Console version 2.0.1 and newer. Older versions do not support the API.  Currently Console version 2.0.1 supports API version 1.0.

The Console REST APIs perform all calls over HTTPS and require the username and password of a valid Console account.  The operations that can be completed are limited by the user's permission levels in Console.

Console 3.2.0 and later supports token authorization, which means admins can submit the authorization token in the JSON payload when creating a simple (or smart) transfer with the Node API. In the most common use case, the remote (destination) server is configured to require tokens in order to allow transfers. For an example of how to submit the token, see Upload Setup.

Common Repsonse Codes

All responses use standard HTTP response codes, and the commonly used codes used with the Console REST API are seen below.

  • 200 - Success
  • 401 - Bad, Missing, or Locked Username/Password
  • 403 - The Specific Operation allows the current user to know the existence of the item, but they cannot change it.
  • 422 - This is used for other errors and a JSON body is normally returned with details.  However, if no details are returned you can look in the mongrel logs

Response Content

If a response contains content, it is returned in JSON format with UTF-8 encoding.  All times are in in UTC.

 


REST API

TransferList(Start, Stop, Filters)

Nearly identical to Activity view in the Console graphical interface (multi-step Smart Transfers will show up as multiple individual items each with its own ID).

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers?from=2013-01-01%2012:00:00&to=2013-01-01%2013:00:00&filter1=status&comp1=eq&val1=inactive

Query Parameters

  • from - UTC Date/Time, "2013-02-28 12:00:00"
  • to - UTC Date/Time, "2013-02-28 12:30:00", if blank current time will be used
  • additional_filters
    • filter1 (field to filter against: started_at | stopped_at | status | transfer_name | contact | filename)
    • comp1 (comparison to use:  contain | eq | gt | gte | in | lt | lte | is_not_null | is_null | match_re | neq | start_with)
    • val1 (value to compare with, e.g.: "running")
    • filter2 (all filters are joined by AND)

Comparator Descriptions

contain
contains (only valid for text fields, not filenames)
eq
equals
gt
greater than (or alphabetically after, for text fields)
gte
greater than or equal to
in
is one of a list of values (separate values with commas)
is_not_null
is not null
is_null
is null
lt
less than (or alphabetically before, for text fields)
lte
less than or equal to
match_re
matches regular expression (only valid for text fields, not allowed for filename)
neq
not equal to
start_with
starts with (only valid for text fields)

Filter Requirements

  • 'from' is required
  • 'to' is optional if 'from' is less than 24 hours ago, otherwise it is required and must be no later than 'from' + 24 hours
  • All datetimes are interpreted as UTC unless time zone is specifically included in the parameter, e.g. "2013-02-28 14:00 -0800". However, it is recommended that you convert datetimes to UTC and then pass them to the API without the timezone (e.g. "2013-02-28 22:00")
  • All query parameters must be URL encoded. For example,  spaces replaced with "%20"
  • Certain filter specifications are not allowed due to performance considerations. For example,  filter = 'filename' and comp =  'match_re'

Reply

If Success; an Array with the list of transfers represented by hashes and containing summary information on each one is returned. An example of this Array is seen below. If Error, a description of the problem will be returned if available.

 

 


TransferDetails(Job_Step_ID)

Nearly identical to the drill-down detail screen for a transfer.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/885278

Reply

If Success, a hash with the details of the transfer is returned, an example of this is seen below. If Error, an error code is returned, normally 422.

 

Descriptions of Reply Fields

bytes_transferred
Total bytes actually transferred over network. Bytes that were already present at the destination at the start of the transfer are not counted if the transfer was started with 'resume' option enabled.
bytes_written
Total bytes completed and have been written to the disk at the destination. May be larger than 'bytes_transferred' because it includes bytes that were already present at the destination (i.e. of files were already there or this is a retry for an interrupted transfer)
contact
Contact as shown in Console UI, generally either an ssh account or Console/Faspex username. Can be affected by cookie parsing rules.
destination
IP address of destination machine
error_description
Error description as shown in Console UI
eta
Estimated time for the transfer to complete based on the current actual rate and 'total_bytes'. Depends on presence and accuracy of 'total_bytes' (see below)
id
Console's numeric id for the transfer.
last_calculated_rate_bps While a transfer is running, Console will attempt to periodically calculate the current actual (as opposed to target) transfer rate by comparing how much the bytes_transferred and microseconds_elapsed have changed since the last time Console checked the transfer. This field is supplied as a convenience to allow users to see approximate current achieved rate. For short transfers the Console may not get a chance to compute this value before the transfer ends - in this case, this field will return null. If you wish to calculate average bitrate for the entire transfer, use (bytes_transferred * 8) / (stopped_at - started_at) instead.
name
Name of the transfer as shown in Console UI. Can be affected by cookie parsing rules.
queued_at
Time that a transfer was first placed on a queue. Null for transfers not started from Console UI/API.
scheduled_start_at
Time that a transfer is/was scheduled to start. Null if the scheduled start time was not specified or transfer was not started from Console UI/API.
source
IP address of the source machine
source_paths
List of specified source items from the ascp command that started the transfer. NOTE: This value is truncated to approximately 4KB so it may not contain the full list.
started_at
Start time of the first session. Null if no transfer session has started yet or if managed node failed to log transfer.
started_via
'Started via' field as shown in Console UI. Can be affected by cookie parsing rules.
status
Status of transfer as shown in Console UI.
submitted_at
Time that the transfer was submitted to Aspera Central by the initiating managed node (i.e. the client). Null for transfers not started from Console UI/API.
stopped_at
Stop time of the last session. Null if the session is still running, no session has started yet or if the managed node failed to log the transfer.
total_bytes
Total bytes to transfer, as computed by the source node at the start of the current transfer session. The source node must be configured to provide this information, otherwise the value will be null. This value might be inaccurate (too low) for hot folder transfers, particularly Windows push hot folders, as it may take more than one session to transfer all files. It may also be inaccurate if files are added/deleted from source directory while the transfer session is running.

 


TransferFileList(Job_Step_ID, Path_Match, Errors_Only, Offset, Limit)

Nearly identical to the file list at the bottom of the transfer details page.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/5/files?offset=20&limit=100&errors_only=true&path_match=foo

Query Parameters

  • offset - how many files to skip (for pagination)
  • limit - (required) max number of items to return (for pagination, and to protect against overwhelming server). Max value is currently 100.
  • errors_only - return only files with errors
  • path_match - string to match anywhere in file path

 Reply

If Success, a list of files are returned; as seen in the example below.

 

 


TransferStart(Job_Step_Id)

Equivalent to clicking 'start' for a scheduled transfer on the Activity page. This starts a scheduled transfer immediately instead of waiting.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/start

 


TransferPause(Job_Step_Id)

Equivalent to clicking 'pause' for a transfer on the Activity page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/pause

 


TransferCancel(Job_Step_Id)

Equivalent to clicking 'cancel' for a transfer on the Activity page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/cancel

 


TransferResume(Job_Step_Id)

Equivalent to clicking 'resume' for a transfer on the Activity page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/resume

 


TransferRerun(Job_Step_Id)

Equivalent to clicking 'rerun' for a transfer on the Activity page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/rerun

Reply

If Success, the ID of the new Transfer is returned, as shown below.

{"id" : 35}

 


TransferChangeRate(Job_Step_Id, Min_Rate, Target_Rate)

Equivalent to entering a new target rate in the chart found on the transfer's Detail page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/change_rate

An Example Body Request

Both parameters below are strings and are required. min_rate_kbps can normally be set to "0".

{  "min_rate_kbps" : "0",  "target_rate_kbps": "100"}

 


TransferChangePolicy(Job_Step_Id, Policy)

Equivalent to choosing a new policy in the chart found on the transfer's Detail page.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers/12/change_policy

An Example Body Request

The policy parameter is required.

{  "policy": "Fair | Fixed | Trickle"}

 


QueuedTransferMoveForward(Queue_Id, Job_Step_Id)

Equivalent to clicking 'Move Up' on a transfer in the displayed queue.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/queues/5/items/12/move_forwards

Reply

If Success, HTTP Status Code 200 (OK). If Error, HTTP Status Code 403 if the user does not have permission to reorder the queue or HTTP Status Code 422 if a different error occurred.

 


QueuedTransferMoveBack(Queue_Id, Job_Step_Id)

Equivalent to clicking 'Move Down' on a transfer for a displayed queue.

Request (PUT)

An Example URL

https://console.asperasoft.com/aspera/console/api/queues/5/items/12/move_back

Reply

If Success, HTTP Status Code 200 (OK). If Error, HTTP Status Code 403 if the user does not have permission to reorder the queue or HTTP Status Code 422 if a different error occurred.

 


QueueContents(Queue_Id)

Returns a list of items in the queue.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/queues/5/items

Reply

If Success, a list of items in the queue will be returned with the frontmost item first. The item_id and whether the item is waiting for this queue or not is returned. Waiting might be false for this queue but items may not be running if the queue is waiting on a second queue or waiting to retry.

 

 


SshKeyList()

Retrieve the list of ssh keys available to use with the SimpleTransferSubmit call.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/ssh_keys

Reply

If Success, an array of the SSH Keys is returned, an example is seen below.

 

SimpleTransferSubmit

When submitting a transfer using the SimpleTransferSubmit API call you may need to include additional fields, these fields are listed below.

  • If an endpoint has a null value for "credential_type" you will need to supply the "password" or "ssh_key_id" field.
  • If an endpoint has an "ip_address" of "*" then you will also need to supply the "ip_address" field.
  • If an endpoint has a "user" of "*" then you will also need to supply the "user" field.

 


EndPointList()

Retrieves a list of endpoints that are available to use with the SimpleTransferSubmit call.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/endpoints

Reply

If Success, an array of the endpoints is returned, an example is seen below.

 

Explanation of Values

  • "dest" - whether the endpoint can be used as a destination
  • "endpoint_type" - "Personal" = created by the user, "Node" = created by Console admin
  • "source" - whether the endpoint can be used as a source

SimpleTransferSubmit

When submitting a transfer using SimpleTransferSubmit API call you may need to include additional fields as seen below.

  • If an endpoint has a null value for "credential_type" you will also need to supply the "password" or "ssh_key_id" field.
  • If an endpoint has an "ip_address" of "*" then you will also need to supply the "ip_address" field.
  • If an endpoint has a "user" of "*" then you will also need to supply the "user" field.

 


SimpleTransferSubmit(Details)

Equivalent to starting a simple transfer in the Console interface.

Request (POST)

An Example URL

https://console.asperasoft.com/aspera/console/api/transfers

An Example Body Request

 

Reply

If Success, the ID of the new transfer is returned; as seen below. If Error, a HTTP Status Code of 422 is returned.

{"id" : 35}

 


SmartTransferList()

Retrieves the list of Smart Transfers that the user is allowed to start.

Request (GET)

An Example URL

https://console.asperasoft.com/aspera/console/api/smart_transfers

Reply

If Success, an array of Smart Transfer IDs is returned including the ID, name and owner.

 

 


SmartTransferSubmit(Smart_Transfer_Id, Details)

Nearly identical to starting a simple transfer in the Console interface, but with fewer options to overriding the settings. It is important to note that if a transfer does not allow the user to select the source items at start, then including a "source" section will result in an error being returned when using this call.

Request (POST)

An Example URL

https://console.asperasoft.com/aspera/console/api/smart_transfers/1

An Example Body Request

 

Reply

If Success, an array of IDs of the new transfer(s) is returned. If it is a multi-step Smart Transfer then multiple transfers will be created.

 

 


Sample Code

TransferList

This example shows how to get a transfer list using Ruby.

 

 


TransferShow

This example shows how to display transfers using Ruby.

 

 


QueueContents

This example shows how to get the queue of transfers using Ruby.

 

 


QueuedTransferMoveForward

This example shows how to move a transfer forward in the queue using Ruby.

 

 


TransferChangePolicy

This example shows how to change the policy on a transfer using Ruby.

 

 


SimpleTransferSubmit

This example shows how to transfer a file using Ruby.

 

 


Video player

Video

×