Overview

Files API

The Files API allows developers to create web applications and automation tools for use with Aspera Files. The Files API supports managing workspaces, users and groups as well as creating packages and managing and submitting to dropboxes. Files also supports a high level of access control for all aspects of your organization setup.  Files is a SaaS (Software as a Service) offering from Aspera. To learn more about Files please visit the Aspera Files sales page or view the Introduction to Files video.

The Files API works closely with the Node API to create a seamless experience between the Files application and the underlying Node. Note that most file operations used in any Files API-based application also uses the Node API. More information about the Node API can be found in the Node section.

 


Authentication

Authentication

To use the Files API you must register your app to get an ID and Secret to be used in the authentication workflow. The Files API uses OAuth 2.0 for authentication and authorization. You must obtain an Access Token (sometimes referred to as a Bearer Token) to authenticate a user and make calls to the Files API. Note that the Files token cannot be used for making calls to Node.  You must obtain a separate token for making calls to the Node API; find more information in the Node API section.

Registering 

To register your app, log in to the administration side of Files for your Organization. From the Organization page click the API Client tab. From here you can create a new client and see your past clients.  Fill out the form and submit; the new client registration will appear in your registered clients list. Click on any entry to get the ID and Secret that you need to use in your app. You can update your redirect URIs also at any time to continue to use the same ID and Secret.

Setting up Your Client

Once you have your client ID and Secret, you can set up your client to use the OAuth flow with Files, which will provide a token that you can use for the session.  You can set up your OAuth login for your client in whichever server-side language you prefer, using any existing OAuth client library or one of your own.

Obtaining an Access Token

To allow your client to obtain an OAuth Access Token you need to follow the normal OAuth 2.0 flow.  The basics of this flow are outlined below.

  1. Direct the end user to the organization's OAuth2 authorization endpoint including the organization name, client identifier, desired scopes, local pass-through state, and a redirect URI. An example of this URL is seen below:
    /api/v1/oauth2/example_org/authorize?client_id=example_client&scope=user%3Aall&redirect_uri=https%3A%2F%2Fexample.com%2Foauth2-callback&response_type=code&state:ABC
  2. The user may be prompted to authenticate and authorize the client access to the scope requested.
  3. The end user will be redirected to the redirect_uri from the URL used in the first step with the authorization code, scopes granted, and the local pass-through state as query parameters:
    /oauth2-callback?code:XYZ&state:ABC&scope:user%3Aall
  4. Exchange the authorization code for an Access Token, which can be used to access the Files API.

Access Tokens

An Access Token is a zipped and base64-encoded blob. When decoded, the token has two parts: a JSON part and a base64-encoded signature. The two parts are divided by the last occurrence of the \n==SIGNATURE==\n, where \n represents the newline character. As far as the end user is concerned, the Access Token is simply a large blob of data required to communicate with the server.  An example of a decoded token is shown below (comments are added, but are not normally included):

 

Authorization Scope

The Authorization Scope specifies which resources an Access Token can access. Note that a server may provide a token with fewer scopes than requested. The most common scopes used in the Files API are provided below.

  • self - Allow access to /self endpoint only 
  • user:all - Allow access to authenticated user's resources
  • admin:all - Allow access to restricted areas, this scope will require a shorter expiration time on the token

 


Conventions

Conventions

The Files API maintains REST-based convention across all of the endpoints to facilitate rapid development of applications making use of the API.  This means that most endpoints support the normal HTTP requests for creating, reading, updating, deleting and querying.  These conventions are explained below.

Supported Formats

The Files API requires that all requests conform to HTTP/1.1 using application/json type for all data.  The Files API also returns all data in JSON format.  The Files API does not support XML.

The Files API supports ISO 8601 format for date and time settings and will return all dates in this format. All dates returned are in the UTC time zone and requests can include time zone offset in relation to UTC. An example of supported date formats are seen below:

  • Date Only: YYYY-MM-DD
  • Time Only: hh:mm:ss
  • Date and Time: YYYY-MM-DDThh:mm:ssZ

Error Responses

If a request causes an error on the Files API, one of the following error codes will be returned.  All normal errors in the Files API will include a response stating the code and a message that can be used in the application for error handling.  In addition to the normal code and message returned, a validity error will return an array of errors explaining which field was invalid and why it was returned as invalid.

  • 400 - Bad Request: The request has malformed/unrecognized syntax or is missing required information for processing the request.
  • 401 - Unauthorized: The user is not logged in or the user session has timed out.
  • 403 - Forbidden: Insufficient permissions; The user is not allowed to perform the requested operation, usually due to not having the correct permissions
  • 404 - Not Found: The resource does not exist at this time. This could mean that the user did not have permission to see that resource, and for security reasons the server is preventing a client from discovering by guessing.
  • 409 - Conflict: A resource already exists that would prevent this resource from being created.
  • 422 - Unprocessable: Entity Invalid Properties for a Create or Update operation.
  • 500 - Internal Server Error: The server has encountered an unexpected or unrecoverable error. This error may result in no code or message being returned in the body response.

Embedding Objects

Most resources support having related objects embedded in their response to optimize client network connections. This means that you can make a call to Users with an embed of Workspace to include the Workspace object related to the workspace_id returned with the User object. Multiple embed options can be included in the embed array. An example of an embed of a Workspace into a User object is shown below.

GET /users?embed%5B%5D=workspace

Pagination

Pagination is available for most collection resources in the Files API.  To paginate a query the 'page' variable needs to be included with the query. Currently the default per_page is set to 50; however, a client should not rely on this behavior in their logic and for best practice should explicitly set a per_page for pagination. To get the total count of items in the collection for the query a header named 'X-Total-Count' is returned that includes the total number. An example of pagination is shown below:

GET /resources?page=1&per_page=10

Sorting

Sorting is available for most collection resources in the Files API. To sort a query the 'sort' variable needs to be included with the query. This variable should be set to a valid property that is sortable. Second-level sorting can be accomplished by separating sorting items by commas. For example, you could sort by date and then by name by using 'sort=date,name'. You can also reverse the order of any sort by including a dash in front of the field name. For example, to sort by date in reverse you can use 'sort=-date'. It is important to note that not all fields can be sorted and invalid sort filters could result in a 422.

GET /resources?sort=date,-name

 


File Management

File Management

A user who is a member of a Workspace has access to a home folder within that Workspace where they can upload, download, share and delete files.  This section covers the normal flow of how to get access to a Home Folder.

 


Home Folder

To find a user's Home Folder you need the node_id and file_id. These can be obtained by doing a GET on /self, which will return information about the current user, including their default Workspace and the Home Folder for that Workspace.

An example of this is included below. The embed array option is used to include the default_workspace object in the returned response. If the user belongs to multiple Workspaces you can obtain the Home Folders for the other Workspaces by performing a GET on the /workspaces endpoint.  Once you have the file_id and node_id you need to get the information on the Node.

Method: GET
Endpoint: /self

Example Response

 

 


Node

Once you have the file_id and node_id you need to get the details on the Node so that you can access the Home Folder for the user.  Once information on the Node is obtained you will need to get a bearer token for granting access to the Node.

Method: GET
Endpoint: /node/308

Example Response

 

 


Bearer Token

Once you have information on the Node you need a bearer token to gain access to the Node. To obtain a bearer token you can do a POST on the token endpoint. You need to construct a scope from the Node's access key.

Method: POST
Endpoint: /oauth2/{organization}/token

Example Request

 

Example Response

 

 


Browsing Files

Once the Node and bearer token are obtained you can get info on, or browse an item on the Node.  Using the Node URL, you can make a GET against the home_file_id or any file_id that the user has access to. It is important to note that the access key needs to be sent as the 'X-Aspera-AccessKey' header.

To learn more about the Node API, please see the Node REST API documentation.

File Info

Method: GET
Host: Node Host
Endpoint: /files/310
Header: X-Aspera-AccessKeys: {access_key}

Example Response

 

Browse Directory

Method: GET
Host: Node Host
Endpoint: /files/310/files
Header: X-Aspera-AccessKeys: {access_key}

Example Response

 

 


Uploading and Download Files

Content can be uploaded or downloaded from any file or folder a user can access using an Aspera transfer API.  You can use the information obtained from the Node and the bearer token to create a transfer_spec that can be used with any Aspera transfer API.

This example uses the Connect JavaScript API; however, any transfer API can be used.

Connect JavaScript Transfer
Method: POST

Example Request

 

Example Response

 

 


Sharing - Finding Recipients IDs (contacts)

A user can share a folder with another user or group within the Files Organization.  However, in order to share with another user or group the recipient's ID needs to be obtained. Users and groups can be discovered using the contacts endpoint.

The contacts endpoint can be used to query for a user or group to retrieve the ID for other users and groups in the Files Organization; to query, use the 'q' variable with a string representing the name or email. You can also use the current_workspace_id variable to include a Workspace ID and get back whether the contact is a member of that Workspace.

Method: GET
Endpoint: /contacts

Example Response

 

 


Sharing - Creating Permissions

To give another User or Group access to a folder on Node you must create a permission granting access to that User or Group. Files automates the background processes of monitoring Node and tracking shares across the Files application as long as the permission is tagged with the workspace ID, shared as name and ID of the user sharing the folder.

To create a permission, make a POST to the permissions endpoint on the Node that has the folder in question.  It is important to note that the access key needs to be sent as the 'X-Aspera-AccessKey' header.

Method: GET
Host: Node Host
Endpoint: /permissions?file_id={file_id}
Header: X-Aspera-AccessKeys: {access_key}

Example Request

 

Example Response

 

 


Files API Docs

To view the API documentation, please select the version you wish to view

 


Packages

Packages

Users who are members of a Workspace can send and receive packages within that Workspace. Once a package is sent it cannot be altered; it can only be archived by the recipient or sender or deleted by the original sender. Use the File and Node ID (retrievable in the Package object) to download the content of a package using any Aspera transfer API.

 


Viewing all Packages

All packages for the current user can be retrieved via a GET on the packages endpoint. The packages endpoint supports multiple queries to limit what is returned to help find specific packages. Once you have a specific package, you can obtain more details by going to the packages/317 endpoint. You can download the package contents from Node by using the returned file_id and node_id. An example response is shown below.

Method: GET
Endpoint: /packages

Example Response

 

 


Viewing a Specific Package

To get the specifics for a certain package, or to update and delete package contents, use the packages/{package_id} endpoint. Once a package is marked as 'sent:true', only certain elements of a package can be updated. Note that package deletion removes only the contents from a package and does not remove the package entry.

Updating a Package

Package information can be updated once created; however, once 'sent' is set to 'true' the only attributes that can be updated are 'archived' and 'read'.

Deleting a Package

A DELETE to the packages/{package_id} endpoint will have Files remove all content from that package's file_id on its respective Node. The package will be marked as deleted on the packages endpoint.

Method: GET, PUT, DELETE
Endpoint: /packages/{package_id}

Example Response

 

 


Sending a Package

There are three steps to create and send a package. To begin you need to create the empty package, which will add the package details to Files and create a location on the Node to store the package contents. Once the package directory is created, upload the package contents to the Node using the file_id and node_id returned on package creation. Finally, to have Files send out a new package notification and to lock the package, use a PUT with 'sent:true' for the new package.

Create Package Entry

Doing a POST to the packages endpoint creates a package entry for Files, and Files creates a home for the package content on Node. This call returns a 201 with all of the package information, including the file_id and node_id needed to initiate a transfer to Node.

Method: POST
Endpoint: /packages

Example Request

 

Example Response

 

Upload Package Content to Node

Using the returned data from the creation you can intiate a transfer of the package's content to the Node. You can use any Aspera transfer API to transer the content, an example using Connect is seen below.

Method: POST
Connect SDK Transfer

Example Request

 

Marking a Package as Sent

At any time during or after the transfer you can mark the package as 'sent', which will lock it and make it unable to be updated (except for marking as 'archived' or 'read'). For Files to send a 'New Package' notification and make the package available to the packages endpoint, the package must be marked as 'sent'. A notification will not go out until a package is marked as 'sent' and all expected files are uploaded.

Method: PUT
Endpoint: /packages/{package_id}

Example Request

 

 


Packages Download Counts

To get the download counts for a package you can use the packages/{package_id}/download_counts endpoint. This endpoint will return the aggregate metric containing the number of downloads per each user who has downloaded the package or part of the package.

Updating a Package

The following types of metrics are returned with each user indicating their downloads.

  • active - a download is in progress
  • failed - a download was attempted but failed
  • full - the entire package (containing directory) was downloaded
  • partial - some files from the package were downloaded individually

Method: GET
Endpoint: /packages/{package_id}/download_counts

Example Response

 

 


Dropboxes

Dropboxes

A Dropbox is similar to a distribution list, in that when a user submits a package to a dropbox, Files notifies dropbox members that new content is available. Dropboxes also support metadata for the packages to allow for collecting data upon package submission.

 


Dropboxes

All dropboxes that the user can submit to, receive from, or both -- either through direct membership or inherited membership -- can be found using the /dropboxes endpoint. Different parameters can be used to filter the dropboxes returned; for example, you can filter to show only dropboxes associated with a specific workspace by using including the workspace_id parameter.

Note that a user's access level is not returned from the /dropboxes endpoint and therefore an application will not know if a user can submit to, receive from, or do both using this endpoint; for that type of data the /dropbox_memberships endpoint should be used.

View All Dropboxes

Method: GET
Endpoint: /dropboxes

Example Response

 

Create New Dropbox

Method: POST
Endpoint: /dropboxes

Example Request

 

Example Response

 

 


Alter a Dropbox

An organization admin or workspace manager can update or delete a dropbox object by using the /dropboxes/323 endpoint. A PUT can be done against a dropbox to update the dropbox or a DELETE can be done to remove the dropbox.

Get a Dropbox

Method: GET
Endpoint: /dropboxes/323

Example Response

 

Update Dropbox

Method: PUT
Endpoint: /dropboxes/323

Example Request

 

Delete Dropbox

Method: DELETE
Endpoint: /dropboxes/323

 


Dropbox Metadata

Dropboxes support holding metadata fields for collecting additional information during a dropbox submission. The Files API currently supports single text field, text box, dropdown and multiple checkboxes for metadata field types. Metadata can be set by simply including a metadata_schema object in the dropbox. You can update a metadata_schema by doing a PUT to add it or update it on a /dropbox/324, or you can include it in the original POST to create the dropbox.

Add Metadata Schema

Method: PUT
Endpoint: /dropboxes/324

Example Response

 

 


Dropbox Memberships

The /dropbox_memberships endpoint returns all memberships that the current user has access to either for submitting or viewing or both. This will include direct memberships as well as inherited memberships through groups. This endpoint will provide details on access level and whether the user can submit to a dropbox. You can also query to return only dropboxes that the user can submit to by using can_submit_packages=true in the query.

View All Dropbox Memberships

Method: GET
Endpoint: /dropbox_memberships

Example Response

 

Create New Dropbox Membership

Method: POST
Endpoint: /dropbox_memberships

Example Request

 

Example Response

 

 


Change a Dropbox Membership

An organization admin or workspace manager can update or delete a dropbox membership by performing a PUT or DELETE on /dropbox_memberships/326, where 326 is the ID of the dropbox membership. Updates to dropbox memberships can be used to change permissions and access per user or group for any dropbox membership.

Get a Dropbox

Method: GET
Endpoint: /dropbox_memberships/326

Example Response

 

Update Dropbox

Method: PUT
Endpoint: /dropbox_memberships/326

Example Request

 

Delete Dropbox

Method: DELETE
Endpoint: /dropbox_memberships/326

 


Users & Groups

Users and Groups

Users are anyone who uses Files, including any actual user who can login to the system, whether they are administrator, manager or regular user. Groups are collections of users and other groups, allowing for hierarchical permissions.

 


View all Users

Get a list of all users by using the /users endpoint.  This returns all users that the current user has permission to see.  The users endpoint supports multiple query parameters to filter the results returned.

Method: GET
Endpoint: /users

Example Response

 

 


Create New User

Create a new user using a POST to the /users endpoint.  When creating a new user the only required item is 'email'. If the user is created successfully, a 201 with the new user object is returned.

Method: POST
Endpoint: /users

Example Request

 

Example Response

 

 


Change Existing User

You can get a specific user using the /users/330 endpoint. This returns the user object for the specific ID. You can update a user by performing a PUT to the same endpoint; delete a user by performing a DELETE on the endpoint. Note that you can use the /self endpoint as an alias for /users/{current_user_id}

Get User

Method: GET
Endpoint: /users/330

Example Response

 

Update User

Method: PUT
Endpoint: /users/330

Example Request

 

 


View all Groups

You can get a list of all groups by using the /groups endpoint.  This returns all groups that the current user has permission to see.  The groups endpoint supports multiple query parameters to filter the results returned.

Method: GET
Endpoint: /groups

Example Response

 

 


Create New Group

A new group can be created by doing a POST to the /groups endpoint.  When creating a new group the only required item is 'name'. If the group is created successfully a 201 with the new group object will be returned.

Method: POST
Endpoint: /groups

Example Request

 

Example Response

 

 


Change Existing Group

You can get a specific group using the /groups/333 endpoint. This returns the group object for the specific ID. Update a group by performing a PUT to the same endpoint; delete a group by performing a DELETE on the endpoint.

Get Group

Method: GET
Endpoint: /groups/333

Example Response

 

Update Group

Method: PUT
Endpoint: /groups/333

Example Request

 

 


Group Memberships

The group memberships endpoint allows you to view the membership connections between users and groups, and also to add or remove members from a group.  A group or a user can be a member of a group; permissions are inherited from the parent group to the child group or user. By default, the group_memberships endpoint returns the member type and ID.

You can use the embed[] parameter to request that the member be embedded in the returned objects. Technically, workspaces are considered system groups and inheritance can come from these workspaces. To avoid this you can pass in system_group=false to exclude workspaces from being returned for group memberships.

Get a Group's Children

This will return a group's children, which can include users and/or groups. The embed[]=member requests that Files include the member object in the returned objects so that additional calls are not required.

Method: GET
Endpoint: /group_memberships
Parameters: embed[]=member&group_id=334

Example Response

 

Get User's or Group's Memberships

This will return a specific user's or group's inheritance. This will be all of the groups that this user or group is a member of. You can include the system_group=false to avoid workspaces being returned.

Method: GET
Endpoint: /group_memberships
Parameters: embed[]=group&member_id=334&member_type={user|group}&system_group=false

Example Response

 

Create New Group Membership

To create a new membership you need the group's ID that you want to add the user or group to; then POST to group_memberships with the new member's type and ID.

Method: POST
Endpoint: /group_memberships

Example Request

 

Example Response

 

Delete Group Membership

To delete a group membership, perform a DELETE on /group_memberships/{membership_id}. If successful, a 204 will be returned.

Method: DELETE
Endpoint: /group_memberships/334

 


API Docs

Files API Docs

To view the API documentation, please select the version you wish to view

 


Video player

Video

×