Overview

Faspex

The Aspera Faspex REST API provides a set of services that enable you to create and receive digital deliveries via a web interface while using FASP technologies.  Faspex version 3 adds support for JSON objects, creating packages from remote data sources and submitting packages to dropboxes.  The features of faspex 2.X are still available in faspex 3.0.

Authentication

Authentication is done via basic HTTP authentication.  Faspex returns a HTTP response code of 401 (unauthorized) for any request that does contain valid credentials.  The only factor that influences successful authentication is the HTTP response code, while some services may return data in the body of the response for the failure it will generally be ignored by the client.

User Identifiers

For the purpose of addressing packages to recipients Faspex users are identified by their username.  If the recipient is an external user (not in the address book) they will be identified by their email address.  While older versions of Faspex required usernames to be in a user@host format, that is no longer required.

Notification Emails

You can configure Faspex so that you are notified about successful upload or download of the file by the recipient.  These notification emails contain a custom SMTP header that contains the link to retrieve the package information in XML format.  For example: "X-Aspera-Filepkg-Location: https://10.0.123.456:443/aspera/faspex/received/78".

Error Responses

HTTP status codes are returned with the JSON response; as long as the status code is 200 everything has completed successfully.  However, error codes may also be returned; the most common is a 401 "not authorized" error.

 


Client SDK

Faspex Client SDK

The Faspex Client SDK for Java enables your application to easily interact with Faspex services; it provides simple to use setup for utilizing the faspex REST API and creating FASP transfers.  You can quickly learn more about the faspex Client SDK by watching the introduction video. This document contains examples of different services you can make as well as the full API Documentation for your reference.  To get started you will need to download the Java SDK using the Download option below.

 


Download

You can download the Faspex Client SDK for Java using the links below.

 


Send Example

This example shows how to build and send a faspex package.  It also shows how to configure the ExecutorService that will be shared among the instances of faspex Client.  Depending on your needs you can extend this example to include a Thread Pool or other threading strategy.  In the example below the send() method is a non-blocking call since it only returns a basic implementation of java.util.concurrent.Future<DeliveryId>.  If you call waitForTransferToFinish() on the result it will force the execution thread to wait until the operation is finished and the result is returned.  Essentially by doing this you make the send() method a blocking call so you can ensure the operation finished and perform any post handling appropriately.

 

 


Faspex Listener Example

This example shows how the faspex listener extends the AbstractFaspexListener class and how by doing so it is able to intercept the various faspex Events and act upon a specified event if the Event() method is present. An example of the available phases are seen below.

  • SendStart
  • PreprocessingStart
  • Preprocessing
  • PreprocessingDone
  • SendDone
  • Transfer
  • ReceiveStart
  • PostProcessingStart
  • Postprocessing
  • PostProcessingDone
  • ReceiveDone
 

 


Send with Preprocessing Example

This example shows how to set a custom preprocessor that allows pre-transfer tasks to be performed on the item. These tasks can be passive or change the item by modifying the file or any other aspect. For example, the preprocessing task could encrypt the files before they are sent, which would change the filename or path. The example below simply builds on the Send example by registering the preprocessor and including the metadata items that will be used by the preprocessor. The new lines are surrounded by "////////////" to demarcate them from established content.

 

 


Preprocessor Example

This example shows how to implement a custom preprocessor. This preprocessor is given access to the faspex Listener located in the faspex Client. This is used to send regular or custom events back to your application. In the case of custom events, additional code may need needed to unpack the item's content. Preprocessors can be passive or actually modify the item being transferred. Preprocessing phases are wrapped in between the SendStart and SendDone phases and are only triggered if the preprocessor is registered.

 

 


Sign On Example

This example shows how to obtain the user's permissions and the capabilities of the server. Signon requires a faspex license be provided and therefore is only recommended if needed.

 

 


Faspex Client SDK Documentation

This section provides the documentation for the Java Faspex Client SDK.

To view the documentation, click the link below:

 


Guides

Sending Packages

The ability to send files and directories as a package to a list of recipients is one of the features that Faspex offers.  The Faspex API allows developers to integrate this capability into their own applications.  This allows developers to build and send packages and offer confirmations messages and other services within their own applications.  This is easily accomplished with the API where you can simply encapsulate the common details into a JSON object that represents the Faspex package and send the package to the server for processing.

When using a Faspex server you can send files that are on your local machine; this is called local-to-remote package delivery, or send files that are on a remote server; this is called remote-to-remote package delivery.

Local to Remote Package Delivery

When performing local-to-remote deliveries the paths on the local host are included in the delivery section of the JSON.  An example of this request is seen below.

 

This is sent as POST to the endpoint /aspera/faspex/send, which states the upload but does not trigger it.  You will need to trigger the actual transfer of the package from the client's host to the faspex server.  The response received will contain the section xfer_sessions which will include all of the information you need to start the transfer.  The actual transfer will need to be performed either using the FASPManager SDK, Connect API or your preferred transfer method.  An example of this response is seen below.

 

Remote to Remote Package Delivery

When performing remote-to-remote delivers the ID of the remote server and the paths on the remote server need to be included in the delivery section of the JSON.  If you do not provide an ID of the remote server the operation is assumed to be a local upload from the client's host.  An example of this request is seen below.

 

This is sent as POST to the endpoint /aspera/faspex/send.  If you wish to test this you can use the following cURL example:

curl -k --basic -uadmin:aspera -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://10.0.160.5/aspera/faspex/send -d '{"delivery": {"title": "CorporateSummit","note": "Materials for the summit","recipients": [ "director", "external@email.com" ],"send_upload_result": true,"use_encryption_at_rest": false,"metadata": {"Name": "Summit","Menu": "Option"},"sources": [{"paths": ["presentation.ppt"]}]}}'

In remote-to-remote deliveries the faspex server and remote server negotiate and starts the upload without any other implementations.  The response only contains a link that you can follow to get the status of the package.  An example of this response is seen below.

 

 


Tutorial: Receiving Packages

This tutorial explains how to automate the download of a faspex package and its content from a faspex package download link.  These links are normally in the format of: 

Example: Package recipient has Faspex account

https://FASPEX_SERVER/aspera/faspex/received/DELIVERY_ID/** Example **/https://acme-faspex.com/aspera/faspex/received/4044

Example: Package recipient uses external email

https://FASPEX_SERVER/aspera/faspex/external_deliveries/DELIVERY_ID?passcode=PASSCODE/** Example **/https://acme-faspex/aspera/faspex/external_deliveries/4822?passcode=7e1b56a2206506bcb1d47beb33598b12d2a8507a

A faspex package download is actually a regular FASP transfer using a FASP URL, you might need to build a transfer spec JSON, a XferParams or extract an ascp command from the URL.  Therefore, the first step is to get the FASP URL that corresponds to the faspex package.  To do this you need to send a HTTP GET request to the faspex server using the download URL with an accept header set to application/xml.  After that you will need to generate an authorization token for downloading the package (this token can be generated by a faspex user account).  Finally you will need to start the download using the transfer parameters and the authorization token.


1. Get the FASP URL

Depending on whether or not your recipient has an account with the faspex server will dictate the command you will use.  For example if your recipient has an account you would use /receiveid/246 and if your recipient does not have an account you will use /external_deliveries/{deliveriy_id}?passcode={passcode}.  For example:

##With Account:curl -ki --basic -uMYACCOUNT:MYPASSWORD -H "Accept: application/xml" -X GET https://acme-faspex.com/aspera/faspex/received/4044##Without Account:curl -ki -H "Accept: application/xml" https://acme-faspex/aspera/faspex/external_deliveries/4822?passcode=7e1b56a2206506bcb1d47beb33598b12d2a8507a

This command would yield the response seen below. This response contains the FASP URL for downloading the entire package in the link tag as well as the FASP URL for each of the contents of the faspex package. You can use any XML parser to extract the FASP URLs.

 

2. Generate Authorization Token

A faspex transfer needs to be authorized by the server with a valid authorization token.  The authorization call to the faspex API /aspera/faspex/issue-token?direction=down will generate the needed token.  If the request is successful a download token will be returned, for recipients without faspex accounts an authorization token will need to be requested from the faspex sender or administrator.  For example, you could run the following cURL command using the payload.xml file seen below.

curl -ki --basic -uMYACCOUNT:MYPASSWORD -H "Content-Type: application/vnd.aspera.url-list+xml" -H "Accept: text/plain" -d @payload.xml https://acme-faspex.com/aspera/faspex/issue-token?direction=down

payload.xml

 

3. Start the Download

The FASP URL and the authorization token are now ready to be used to start the download.  Depending on the API/SDK used to download hte content, the FASP URL may be converted into:

  • transferSpec JSON Object, to be used with the Connect JavaScript API
  • XferParams, to be used with the FASPManager SDK
  • Command Line, to be used with ascp

The FASP URL can be processed to create any of the items above.  For more information on how to process the FASP URL please see the FASP URL Syntax page.  For example, if you had the following FASP URL and token:

FASP URL

<link rel="package" href="fasp://faspex@acme-faspex.com:33001/test - 002de384-85ba-4a3c-9239-aae57f657814.aspera-package/PKG - test?cookie=aspera.faspex20:d:176cc5df-2df8-4c09-ae93-2b39f3e0ed7b:dG9ibw:eyJfcGtnX3V1aWQiOiIwMDJkZTM4NC04NWJhLTRhM2MtOTIzOS1hYWU1N2Y2NTc4MTQiLCJfcGtnX25hbWUiOiJ0ZXN0IiwiX2NyZWF0ZWRfdXRjIjoiMjAxNC8wNS8yNiAxMzo0ODozNyArMDAwMCJ9:dGVzdA&port=33001&policy=fair&targetrate=45000&minrate=0&enc=aes128&fallback=yes&httpport=443&auth=no&createpath=no&lockpolicy=yes&lockminrate=yes&bwcap=100000&v=2"/>

Token

ATM2_ACsII-7P2023EThXT4xzcN9Ozs1h2XnpyiEXQpYr2I7W0QAAI3nLg_88FDWsLIFRzIbcGJ_2MTA

With this FASP URL and token you could generate the following transferSpec JSON, XferParams, or ascp command.

transferSpec JSON

 

XferParams (Java)

 

ascp Command

export ASPERA_SCP_TOKEN=ATM2_ACsII-7P2023EThXT4xzcN9Ozs1h2XnpyiEXQpYr2I7W0QAAI3nLg_88FDWsLIFRzIbcGJ_2MTAexport ASPERA_SCP_COOKIE=aspera.faspex20:d:176cc5df-2df8-4c09-ae93-2b39f3e0ed7b:dG9ibw:eyJfcGtnX3V1aWQiOiIwMDJkZTM4NC04NWJhLTRhM2MtOTIzOS1hYWU1N2Y2NTc4MTQiLCJfcGtnX25hbWUiOiJ0ZXN0IiwiX2NyZWF0ZWRfdXRjIjoiMjAxNC8wNS8yNiAxMzo0ODozNyArMDAwMCJ9:dGVzdAascp - O 33001 -P 33001 -l 45000 -m 0 -i privateKeyPath --mode=recv --user=faspex --host=“acme-faspex.com” --policy=fair "/test - 002de384-85ba-4a3c-9239-aae57f657814.aspera-package/PKG - test" /home/Downloads/

 


REST API

REST API

This guide provides reference to all of the services offered in faspex 3.0.  To see these services in action please use the Live Demo link on the left.  As new services are integrated into faspex Server they will appear in this section.

It is important to note that the faspex REST API is not supported for SAML users since faspex does not support headless SAML authentication.

 


Sign-on (API v.3)

This service is used to determine whether a user can access the Faspex Server and whether the client application is allowed. The client application accessing this service passes in its base64-encoded license which is then checked by Faspex to see if the client is allowed. Normal response includes a list of services (same information as returned by the XRDS service) accessible to the user and permissions for the user. A request with invalid user credentials returns a "401 Unauthorized error; all other error conditions result in 200 OK with the error returned in the JSON response . Error codes are standardized across Aspera applications; refer to Error Codes for detailed information.

Note: In version 4.0 of the Faspex API the /signon endpoint returns a metadata profile with the response, by default.

  • Supported Formats: JSON
  • Faspex Support: 2.6.5 +

Request Example

 

Response Example

 

 


Address Book

The address book service will return an XML or JSON formatted list of contacts for a user in response to a GET request that provides correct authentication credentials via HTTP Basic Authentication. The service supports filtering, pagination and sorting according to the portable contacts specification and all queries should be formatted accordingly. A response containing one entry in XML formatting has the structure seen below.  Each contact entry will contain one or two email addresses. The first email will always have the form "<username>@<faspex_host>" and will be marked as the primary email of the contact. In the event that the authenticating user is allowed to send to external emails, a secondary email address external to faspex will be included with some contacts, which is the email address associated with that user's account in Faspex (the email address at which the user normally receives notifications).

The username portion of each email address is url-encoded (or percent encoded), so that any email address returned by the service contains exactly one '@' character, although its username portion may contain additional, encoded '@' signs (to illustrate this point, for a user with username 'greg@gmail.com' the address book will return a listing containing the email address 'greg%40gmail.com@10.0.160.5'). By default, each contact includes a 'tags' field that will include one of the tags; 'workgroups', 'users' or 'external-users'.  These tags correspond to the type of contact in faspex. Contacts' IDs are guaranteed to be unique strings, but no additional specifications are available for IDs. In the faspex 1.7+ implementations, IDs will have the following structure:

  • Normal Users - IDs corresponding to the their ID in the system.
  • Workgroup Users - IDs comprised of their IDs in the system prefixed by the string 'wg'.
  • External Users - IDs consisting of the string 'ex' followed by a number
  • Location: /address-book
  • Supported Formats: XML, JSON
  • faspex Support: 2.X + 

XML Entry Response Example

 

Query/Response Table

Several available queries and the content of their response is presented in the table below.  The path is relative to the address-book service URL.

Path + Query Content of Response
/@me/@self list containing a single entry describing the authenticated user
/@me/@all list containing entries for each contact in the authenticated user's address book
/@me/@all/6 list containing a single entry describing the contact with ID equal to 6 (or an error if no such contact exists in the authenticated user's address book)
/@me/@all?sortBy=displayName&sortOrder=ascending list containing a single entry for each contact in the authenticated user's address book, sorted by their displayName in ascending order
/@me/@all?count=10 list containing a single entry for the first 10 contacts found in the given ordering
/@me/@all?count=10&startIndex=20 list containing a single entry for each of the 10 contacts at indices 20-29 according to the given ordering
/@me/@all?filterBy=displayName&filterOp=startswith&filterValue=sam list containing a single entry for each contact in the authenticated user's address book whose displayName starts with 'sam'

cURL Example

An example cURL command is seen below, this queries the service at the URL https://10.0.160.5/aspera/faspex/address-book/@me/@self?format=xml. In the command below admin:aspera is the credentials for the user admin. The default response format will be JSON, if you wanted to change to XML the format parameter would need to be set to XML.

curl -k --basic -u admin:aspera "https://10.0.160.5/aspera/faspex/address-book/@me/@self?format=xml"

Ruby Example

An example of the same cURL command, but in Ruby programming is seen below.

 

Response

The success or failure of a request will be determined by the HTTP response code. Although faspex may return additional information in the body of a response, this data will be ignored by clients and should not be relied upon. The following table lists the response codes supported by faspex, a description of the situations they cover, and an example query that should trigger that response code.

Response Code Description Example Query
200 (OK) Query succeeded /@me/@all
400 (Bad Request) Invalid query (according to the PC specification) /@invalid_path
401 (Unauthorized) Authentication failed /@me/@all [using invalid credentials]
404 (Not Found) Invalid contact id /@me/@all/2718_invalid_id
500 (Internal Server Error) The server encountered an internal error N/A

 


Send

This service is used for sending packages that have been created from files on a remote source. Same as the send-to-service, except a remote file source and paths need to be specified. Unlike the send-to-service, calling send will actually initiate an upload from the remote source to faspex. The response only indicates the success/failure of transfer initiation, not the result of the upload.

  • Location: /send
  • Supported Formats: JSON
  • faspex Support: 3.0 +

 

Request Example

Below is an example of a Request in JSON format, the source ID is only needed if sending a package from a remote file source. Specifying paths without a source ID will prepare a local upload from the client’s computer. Although the API allows specifying multiple sources for one package, this will be initially unsupported. The current syntax allows for future expansion.

It is important to note that when sending to a Dropbox the dropbox must be the only recipient or an error will be returned stating 'Package creation failed' with an internal message of 'Dropbox recipient must be the only recipient.'

Additional JSON fields that can be enabled server-side by an admin include "delete_after_download"; which could then allow you to specify 0 for do nothing, 1 for delete after all recipients download all of the files, or 2 for delete after any recipients downloads all of the files.  Additional options like "notify_on_[download/upload]" and "notifiable_on_[download/upload]" can be used together for setting notification policies.

 

Response Example

The response for a package submitted from a local client browser is basically a passthrough of the Node API response, with the addition of a generated fasp URL for convenience. A submission from a remote source will not include the xfer_sessions key; rather, only a link to the package status.

 

 


Received Delivery Information

This service is used to obtain the details of an individual received package.

  • Location: /received/[recipient_delivery_id]
  • Supported Formats: XML

 

Request Example

 

Response Example

 

 


Sent Delivery Information

This service is used to obtain the details of an individual sent package.

  • Location: /sent/[delivery_id]
  • Supported Formats: XML

 

Request Example

 

Response Example

 

 


Dropbox Information

This service is used to obtain information on a specific dropbox.

  • Location: /dropboxes/[dropbox_id]
  • Supported Formats: JSON
  • faspex Support: 3.0 +

 

Request Example

 

Response Example

 

 


Dropbox Submit

This service is used to submit a dropbox package, it is essentially the same as Send but is missing the recipients list. Dropbox submission can be created from either a local or remote source.

  • Location: /dropboxes/[dropbox_id]/deliveries
  • Supported Formats: JSON
  • faspex Support: 3.0 +

 

Request Example

 

 


Dropbox Listing

This service is used to list all the dropboxes the account has access to.

  • Location: /dropboxes
  • Supported Formats: JSON
  • faspex Support: 3.0 +

 

Request Example

 

Response Example

 

 


2.x Services

Faspex Services

The Faspex REST API provides a set of services that enable users to create and receive digital items via a web interface while utilizing FASP technology.

 


XRDS Discovery Service

This service offers discovery through the XRDS format which means that faspex will return a XRDS-formatted XML document in response to a GET request on an URL.  Currently this URL is the root faspex URL.

cURL Example

curl -k -H "Accept: application/xrds+xml" "http://10.0.160.5:3000/"

Ruby Example

 

XML Response Example

The XRDS document lists the URLs for all other faspex web service API calls.  If a <am:property type="client-license-required"> property is returned than a license is required to communicate with this faspex server.

 

 


Inbox Service

This service returns an ATOM feed in response to a GET request (proper authentication over HTTP required). The feed lists the packages currently on the faspex server that are categorized under 'inbox'.

cURL Example

curl -k --basic -u admin:aspera "http://10.0.160.5:3000/aspera/faspex/inbox.atom"

Ruby Example

 

XML Response Example

The response should be an XML document formatted accordingly to the ATOM specifications. Each entry will contain at least one link tag, one for each top level file or directory in the package. Additional links describe locations that contain feeds with package listings that are categorized under 'sent' and 'archive'. Currently, faspex will provide access to packages that are 'inbox', 'archive' and 'sent'.

 

faspex 4.x Example

faspex 4.x includes some additional parameters and a slightly different response. An example from faspex 4.x is seen below.

  • Location: /inbox.atom
  • Authentication: Basic (Base64-encoded credentials)
  • Supported Formats: XML
  • faspex Support: 4.0.0+

Parameters

  • count - number of packages to return (default 10)
  • startIndex - the ID of the first package you want returned
  • page - the page you want returned

Response

 

Feeds

Feeds are paginated and will contain links to the next and previous page if it exists. Entries are ordered by package creation date in descending order. This allows clients to follow next links until it finds a package it has already processed and this ensures processing of all packages since the last time a listing was received.

The success of requests should be determined by the HTTP response code. Successful requests will return 200 (OK) and failed requests will return an HTTP status code indicating the reason, for example: 401 for unauthorized or 500 for internal server error. Each package may contain one or more package:property tags which indicate the property of the package. The following properties are currently supported:

  • in-transit - Package is still being uploaded or related and the files are not available for download.
  • error - Uploading of this package has been stopped before all files were uploaded, this is usually caused by user intervention or an error.
  • unopened - The package has not been viewed by the user.

 


Send-To Service

This service allows publishing of content to faspex by POSTing an XML document to the service URL with correct HTTP authentication.

XML Request Example

 

The tags currently supported in the XML Request are:

  • to - specify the content of the tag as a recipient (at least one is required). Valid values are any entries returned by the address-book service, or external emails for users with appropriate privileges. In particular, each user may be specified as a recipient using two different email addresses as described in that section.
  • from - the email address that should appear as the source of the package. If present, it must match the credentials against which the API call was authenticated (optional).
  • subject - the title of the package (required).
  • body - package notes (optional).
  • form - reserved for future use (optional).

cURL Example

curl -k -d @body.xml -H"Accept: application/vnd.aspera.package+xml" --basic -uadmin:aspera "http://10.0.160.5:3000/send-to"

Ruby Example

 

XML Response Example

Upon success the service will set the HTTP response code to 200 (OK) and the body of the response XML will contain a FASP URL describing the transfer that should take place. You should then process to upload the package files by initiating the transfer that is described in the URL. If something goes wrong a HTTP response code of 400 (bad request), 401 (unauthorized), or 500 (internal server error) will be returned. An example of a successful and failed response are seen below.

 

 


Issue-Token Service

Tokens are authorization credentials for transfer sessions. This service is part of a session operation: Client wants to download and it fails due to authorization, then it can request authorization tokens through this service, then proceed with the session. This service is not meant as a preparatory step to get tokens and store them for future use, and are not supposed to be used in other operation.

Client Side Example

 

Server Side Example

The server will respond with an indication of success as seen below. If an error occurs for any reason the response will contain an error code and a message. A list of possible error messages are below.

 

Example Error Messages

Error Conditions Description
unsupported-format Client attempted to post data in a non-xml format.
xml-not-well-formed Error processing the xml.
invalid-url At least one of the URLs is invalid, or refers to content that no longer exists on the server.
unauthorized The user that authenticated with the service is not the original owner of this content.

 


Tools

Live Demo

Below is the API documentation and live demo of the faspex API.

 


Java Command line Tools

The Java Command Line Tools are a set of tools that allow you to query a Faspex inbox and send packages using Faspex. The faspex command-line tools are built using Faspex REST API. The Java source for these tools is available in this package. Developers interested in building applications using the Faspex REST API are free to reuse this source with no restrictions.

Download

Click here to download the Java Command Line ToolsClick here to download the Java Command Line Tools

Requirements

  • Java Runtime Environment 1.5 or higher.
  • ascp installed and added to the system path.

Instructions

  • Copy the included asperaweb_id_dsa.putty private key to the .ssh directory in the user's home directory which will enable token-based authorization.
  • Run f_list, f_get, or f_send.

Build Tools

You can build the tools from the directory of the download, depending on your system you will need to run the following commands:

Linux/Macintosh

  • mkdir classes
  • javac -source 1.5 -target 1.5 -d classes -classpath lib/aspera-frameworks-util.jar:lib/commons-lang-2.4.jar:lib/slf4j-api.jar:lib/slf4j-nop.jar:lib/aspera-faspmanager.jar src/com/asperasoft/samples/faspex/cmdclient/*.java
  • cp src/com/asperasoft/samples/faspex/cmdclient/*.txt classes/com/asperasoft/samples/faspex/cmdclient/
  • jar cfm lib/aspera-faspex-cmdclient.jar manifest -C classes .

Windows

  • mkdir classes
  • javac -source 1.5 -target 1.5 -d classes -classpath lib\aspera-frameworks-util.jar;lib\commons-lang-2.4.jar;lib\slf4j-api.jar;lib\slf4j-nop.jar;lib\aspera-faspmanager.jar src\com\asperasoft\samples\faspex\cmdclient\*.java
  • copy src\com\asperasoft\samples\faspex\cmdclient\*.txt classes\com\asperasoft\samples\faspex\cmdclient\
  • jar cfm lib\aspera-faspex-cmdclient.jar manifest -C classes .

 


Command Line Client

IBM Aspera Command-Line Interface

The IBM Aspera Command-Line Interface (CLI) is a lightweight shell scripting tool that be used to automate Faspex and Shares tasks without having to do additional coding. The CLI is for users and organizations that want to automate their transfer workflows; it provides an alternative to using the API for the same functionality.

For more information, see the IBM Aspera CLI User Guide (select your platform and transfer server version to access the document link).

 


Sample Program

Sample Program

This Java sample program demonstrates how to use faspex 3.0 in conjunction with the FASPManager APIs to create and send a package to recipients as well as how monitor the package.  This useful all in one example is a great starting point for your projects and to allow you to quickly build your own program by building off of this example.  This document will provide the option to download the full program, system requirements and a quick overview of the different classes used.  For more information on specific API calls please see the API guides on the left.

Download

To begin you will need to download the Java Sample code.  This code will need to be compiled and can be either imported into your favorite Java IDE or be compiled using a command prompt.

System Requirements

In order to run this program you will need to ensure the machine meets the following conditions:

  • Has the Java Runtime Environment version 1.5 or higher
  • Has ascp installed and on the system path
  • Has a copy of the asperaweb_id_dsa.putty private key in the .ssh directory in the user's home folder (this is needed for token based authentication)

Overview

To help you get started we will cover the main components of this program and what they are for.  This will help you quickly find the sections pertinent to what you are trying to accomplish. When you download the sample from below you will find all of the Java files in the src directory and all of the dependent library files in the libs directory. Some of the more pertinent Java files are seen below.

SubmitJob.java

This class is the driving force for the application.  It handles most operations and more importantly contains the variables that you need to set for your application to talk to your faspex server. If transferFromLocal is set to true then a client to server upload is performed via FASPManager, however, if false then a server to server transfer will take place with the source being the ID that corresponds to sourceShareID. It should be noted that even with a server to server transfer we are still able to monitor the progress of the transfer.

 

SendData.java

This class contains the helper methods used to create the JSON package request that describes the faspex package that will be sent to the faspex 3.0 send API.

 

FaspManagerTransfer.java

This class is used to transfer the files using the FASPManager API based on the result of the faspex send API that was performed in SendData.java.

 

 


Resources

Resources

Useful guides and additional resources are found in this section.  This provides you with solutions to common issues and goes into deeper details on certain concepts.

 


 


Video player

Video

×