Differences between Faspex 5 API and previous versions

Edit online

Faspex 4 (and before) integration migration matrix with Faspex 5

Items Faspex 4 and older Faspex 5
Authentication
  • Basic authentication
  • SAML
  • Faspex 5 UI login page
  • SAML
Authorization
  • OAuth flow
  • HMAC-signed bearer token
  • OAuth 2 flow
  • JWT grant flow (with optional impersonation)
API RESTful RESTful with OAS 3.0 file (allows any industry-standard code generator to build client libraries)
API base path /aspera/faspex/api/ /aspera/faspex/api/v5/
Data transfer Use the API to create Faspex packages. Use an Aspera transfer tool or SDK to pick files and perform the transfer. Compatible transfer tools and SDKs are:
  • ascp
  • Connect SDK
  • HTTP Gateway Javascript SDK
  • FaspManagerSDK
 Use the API to create Faspex packages. Use an Aspera transfer tool or SDK to pick files and perform the transfer. Compatible transfer tools and SDKs are:
  • ascp
  • Connect SDK
  • HTTP Gateway Javascript SDK
  • TransferSDK
Sending packages workflows v3
  1. Call POST /send.
  2. Start the upload transfer by mapping JSON response fields directly to transfer tool or SDK fields.
    Note: This procedure is prone to error.
v4
  1. Call POST /api/users/me/packages.
  2. Call POST /api/users/me/packages/{package_id}/transfer_specs with {"direction": "send"} in the request.
  3. Start the upload transfer by mapping JSON response fields directly to transfer tool or SDK fields.
    Note: This procedure is prone to error.
  1. Create a package by calling POST /packages.
  2. Retrieve a valid transfer specification by calling POST /packages/{id}/transfer_spec/upload
  3. Start the upload transfer by passing the retrieved
    1. or passing directly the transfer_spec JSON response to Connect API AW.Connect#startTransfer : (safe)
    2. or passing directly the transfer_spec JSON response to Transfer SDK StartTransfer : (safe)
Receiving package API calls followed by a FASP transfer for package sending or receiving use casesAPI-only calls for all the other use cases API calls followed by a FASP transfer for package sending or receiving use casesAPI-only calls for all the other use cases
SDK Java SDK with support for a limited number of API endpoints Effort is done in making easy the code generation covering the entire API endpoints. Example provided.

Authentication and authorization

Faspex 5 adopts OAuth 2 as the authorization mechanism for its APIs. The Faspex V3 API used less-secure HTTP basic authorization and the Faspex V4 API did not decouple user authentication from authorization.

An administrator can register an API client to retrieve a bearer token to interact with the endpoints. The bearer token can be obtained through either a JWT grant flow, an authorization code flow or an authorization code with PKCE (Proof Key for Code Exchange) flow. See Authentication and authorization.

API differences

Packages API

In the Faspex 5 API, packages are handled by top-level endpoints and do not require you to identify packages by ownership (such as user or workgroup). Faspex 5 expects you to directly interact with packages using the package ID. Package availability is based on the role of the current logged-in user. This change makes it easier to work with packages, but may require those migrating from Faspex 4 to use several endpoints to achieve the same goal.

Enhancements to search and scoping are planned for a future release of Faspex 5.

Endpoint
API calls
View all packages (admin search)

Faspex 4

POST /api/packages/

Faspex 5

GET /api/v5/all/packages

Reference

Get all packages of a user

Faspex 4

GET /api/users/{user_id}/packages/

Faspex 5

  • See all packages available to you as the current user: 
    GET /api/v5/packages

    Reference

  • As an admin, see all packages available to another user:

    GET /api/v5/packages?q=username
    The q query parameter searches sender and recipient user fields.

    Reference

View all packages (admin search)

Faspex 4

POST /api/packages/

Faspex 5

GET /api/v5/all/packages
Reference
Get all packages of a user

Faspex 4

GET /api/users/{user_id}/packages/

Faspex 5

See all packages available to the current user: 
GET /api/v5/packages

Reference

As an admin, see all packages available to another user:
GET /api/v5/all/packages
Sort the response based on recipient user IDs.

Reference

Get a package of a user

Faspex 4

GET /api/users/{user_id}/packages/{package_delivery_id}

Faspex 5

Search for the package using the package ID: 

GET /api/v5/packages/{package_id}

Reference

Create a package

Faspex 4

POST /api/users/{user_id}/packages

Faspex 5

POST /api/v5/packages

Reference

Delete a package of a user

Faspex 4

DELETE /api/users/{user_id}/packages/{package_delivery_id}

Faspex 5

DELETE /api/v5/packages/{package_id}

Reference

Delete a package from a dropbox

Faspex 4

DELETE /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}

Faspex 5

DELETE /api/v5/packages/{package_id}

Reference

Delete all packages of a user

Faspex 4

DELETE /api/users/{user_id}/packages

Faspex 5

  1. Get a list of packages:
    • See all packages available to you as the current user: 
      GET /api/v5/packages

      Reference

    • As an admin, see all packages available to another user:

      GET /api/v5/packages?q=username
      The q query parameter searches sender and recipient user fields.

  2. Delete multiple packages using their package IDs: 

    DELETE /api/v5/packages?ids={package_id, package_id, package_id...}

    Reference

Delete all packages from a dropbox

Faspex 4

DELETE /api/dropboxes/{dropbox_id}/packages

Faspex 5

  1. Get packages for a shared inbox:
    GET /api/v5/shared_inbox/{shared_inbox_id}/packages

    Reference

  2. Delete multiple packages using their package IDs:

    DELETE /api/v5/packages?ids={package_id, package_id, package_id...}

    Reference

Update and edit package attributes, recipients, and metadata of a user

Faspex 4

PUT /api/users/{user_id}/packages/{package_delivery_id}

Faspex 5

PUT /api/v5/package/{package_id}

Reference

Update and edit package attributes, recipients, and metadata from a dropbox

Faspex 4

PUT /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}

Faspex 5

PUT /api/v5/package/{package_id}

Reference

Search for a package of a user

Faspex 4

GET /api/users/{user_id}/packages

Faspex 5

Search for packages available to the current user with different filters: 
GET /api/v5/{mailbox_type}/packages

Reference

Search for a package in a dropbox

Faspex 4

GET /api/dropboxes/{dropbox_id}/packages

Faspex 5

Search for packages in the shared inbox with different filters: 

GET /api/v5/shared_inbox/{shared_inbox_id}/packages

Reference

Sort the response based on recipient types.

Forward a package of a user

Faspex 4

POST /api/users/{user_id}/packages/{package_delivery_id}

Faspex 5

POST /api/v5/packages/{id}/forward

Reference

Forward a package in a dropbox

Faspex 4

POST /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}

Faspex 5

POST /api/v5/packagess/{id}/forward

Reference

Replicate package contents of a user

Faspex 4

POST /api/users/{user_id}/packages/{package_delivery_id}/replicate_contents

Faspex 5

Not currently available in Faspex 5.

Replicate package contents in a dropbox

Faspex 4

POST /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}/replicate_contents

Faspex 5

Not currently available in Faspex 5.

Delete the files and folders from a package

Faspex 4

POST /api/users/{user_id}/packages/{package_id}/delete_contents

Faspex 5

Not currently available in Faspex 5.

Rename package contents

Faspex 4

POST /api/users/{user_id}/packages/{package_id}/rename_contents

Faspex 5

Not currently available in Faspex 5.

Get transfer specification needed for a package transfer

Faspex 4

POST api/users/{user_id}/packages/{package_id}/transfer_specs

Faspex 5

Uploads: 

POST /api/v5/packages/{package_id}/transfer_spec/upload

Reference

Downloads: 
POST /api/v5/packages/{package_id}/transfer_spec/download

Reference

Get package transfer history (for transfer sessions) for users

Faspex 4

GET /api/users/{user_id}/packages/{package_delivery_id}/transfers

Faspex 5

Uploads: 

POST /api/v5/packages/{package_id}/upload_details

Reference

Downloads:

POST /api/v5/packages/{package_id}/download_details

Reference

Get package transfer history (for transfer sessions) for dropboxes

Faspex 4

GET /api/dropboxes)/{dropbox_id}/packages/{package_delivery_id}/transfers

Faspex 5

Uploads: 

POST /api/v5/packages/{package_id}/upload_details

Reference

Downloads: 
POST /api/v5/packages/{package_id}/download_details

Reference

Initiate a remote content upload for a user package
Faspex 4
POST /api/users/{user_id}/packages/{package_delivery_id}/transfers

Faspex 5

POST /api/v5/packages/{package_id}/remote_transfer

Reference

Nodes API

Shares are now called shared folders or storage locations in Faspex 5.
Endpoint
API calls
Get all nodes

Faspex 4

GET /api/nodes

Faspex 5

GET /api/v5/nodes

Reference

Get shares for a given node

Faspex 4

GET /api/nodes/{node_id}/shares

Faspex 5

GET /api/v5/nodes/{node_id}/shared_folders

Reference

Metadata profiles

Get current metadata profiles

Faspex 4

GET /api/metadata_profiles

Faspex 5

GET /api/v5/configuration/metadata_profiles

Reference

Get a metadata profile

Faspex 4

GET /api/metadata_profiles/{id}

Faspex 5

GET /api/v5/configuration/metadata_profiles/{id}

Reference

Get the default metadata profile

Faspex 4

GET /api/metadata_profiles/default_profile

Faspex 5

GET /api/v5/configuration/metadata_profiles/default_profile

Reference

Validate metadata

Faspex 4

POST /api/metadata_profiles/{id}/validate_metadata

Faspex 5

Not currently available in Faspex 5.

Users API

Endpoint
API calls
Get current user info

Faspex 4

GET /me

Faspex 5

GET /api/v5/account

Reference

Sign on (API v.3)

Faspex 4

POST /aspera/faspex/signon/

Faspex 5

Not currently available in Faspex 5.
Find available login methods (API v.3)

Faspex 4

GET /login/new

Faspex 5

GET /api/v5/saml_configs

Reference

Get user contacts (API v.3)

Faspex 4

GET /aspera/faspex/address-book

Faspex 5

GET /api/v5/contacts

Reference

Get users

Faspex 4

GET /api/users

Faspex 5

GET /api/v5/accounts

Reference

Create user

Faspex 4

POST /aspera/faspex/api/users

Faspex 5

POST /api/v5/accounts

Reference

Update user

Faspex 4

PUT /aspera/faspex/api/users/{id}

Faspex 5

PUT /api/v5/accounts/{id}

Reference

Delete user

Faspex 4

DELETE /aspera/faspex/api/users/{id}

Faspex 5

DELETE /api/v5/accounts/{id}

Reference

Get user configuration

Faspex 4

GET /api/users/{id}/configuration or GET /api/users/me/configuration

Faspex 5

GET /api/v5/accounts/{id}

Reference

Shared inboxes (formerly dropboxes) API

List all dropboxes to which an account has access (API v.3)

Faspex 4

GET /aspera/faspex/dropboxes

Faspex 5

GET /api/v5/shared_inboxes

Reference

Get information about a dropbox (API v.3)

Faspex 4

GET /aspera/faspex/dropboxes/{dropbox_id}

Faspex 5

GET /api/v5/shared_inboxes/{id}

Reference

Dropbox and workgroup memberships API

Endpoint
API calls
Get current dropbox memberships

Faspex 4

GET /api/dropbox_memberships

Faspex 5

  • Members:

    GET /api/v5/shared_inboxes/{shared_inbox_id}/members

    Reference

  • SAML groups:

    GET /api/v5/shared_inboxes/{shared_inbox_id}/saml_groups

    Reference

Get current workgroup memberships

Faspex 4

GET /api/workgroup_memberships

Faspex 5

  • Members:

    GET /api/v5/workgroups/{shared_inbox_id}/members

    Reference

  • SAML groups:

    GET /api/v5/workgroups/{shared_inbox_id}/saml_groups

    Reference

Get specific dropbox membership

Faspex 4

GET /api/dropbox_memberships/{id}

Faspex 5

Not currently supported in Faspex 5. Use the API calls to show all members and find the specific member in the response.

  • Members:

    GET /api/v5/shared_inboxes/{shared_inbox_id}/members

    Reference

  • SAML groups:

    GET /api/v5/shared_inboxes/{shared_inbox_id}/saml_groups

    Reference

Get specific workgroup memberships

Faspex 4

GET /api/workgroup_memberships/{id}

Faspex 5

Not currently supported in Faspex 5. Use the API calls to show all members and find the specific member in the response:

  • Members:

    GET /api/v5/workgroups/{shared_inbox_id}/members

    Reference

  • SAML groups:

    GET /api/v5/workgroups/{shared_inbox_id}/saml_groups

    Reference

Create a dropbox

Faspex 4

POST /api/dropbox_memberships

Faspex 5

POST /api/v5/shared_inboxes

Reference

Create a workgroup

Faspex 4

POST /api/workgroup_memberships

Faspex 5

POST /api/v5/workgroups

Reference

Delete a dropbox membership

Faspex 4

DELETE /api/dropbox_memberships/{id}

Faspex 5

Member:

DELETE /api/v5/shared_inboxes/{shared_inbox_id}/members/{member_id}

Reference

SAML group:
DELETE /api/v5/shared_inboxes/{shared_inbox_id}/saml_groups/{saml_group_id}

Reference

Delete a workgroup membership

Faspex 4

DELETE /api/workgroup_memberships/{id}
Faspex 5

Member:

DELETE /api/v5/workgroups/{shared_inbox_id}/members/{member_id}

Reference

SAML group:
DELETE /api/v5/workgroups/{shared_inbox_id}/saml_groups/{saml_group_id}

Reference

SAML configuration API

Endpoint
API calls
Get user profile

Faspex 4

GET /api/user_profile_fields/{saml_configuration_id}
Faspex 5
GET /api/v5/saml_configs/{saml_config_id}/user_profile_fields

Reference

Get current SAML configurations

Faspex 4

GET /api/saml_configurations

Faspex 5

GET /api/v5/saml_configs
Look for the configuration that has default as true.

Reference

Get a SAML configuration

Faspex 4

GET /api/saml_configurations/{id}

Faspex 5

GET /api/v5/saml_configs/{id}

Reference

Faspex services API

Endpoint
API calls
XRDS Discovery Service

Faspex 4

GET /

Authorization: Basic

Accept: application/xrds+xml

Faspex 5

Faspex services are now run in the faspex_services container and not discoverable through the API. You can monitor background jobs using the 
GET /aspera/faspex/health
Reference