AeroFS for Developers


Unleash the power of distributed storage

AeroFS Private Cloud provides a RESTful API for content access and OAuth 2.0 for user authorization. Once an appliance administrator registers your app with the organization's AeroFS Appliance and a user in the organization gives authorization, your app can access the user's AeroFS data by making requests to the API endpoint in the AeroFS Appliance.

How it works

  • Your app makes API requests to the API endpoint in the AeroFS Appliance.
  • The load balancer in the AeroFS Appliance forwards API requests to Team Servers and Desktop clients.
  • A computer is chosen based on your app's consistency policy.

Unlike traditional systems where all the data are stored on a central server, AeroFS replicates files peer-to-peer across all the Team Servers and desktop clients in an organization.

A load balancer running in the AeroFS Appliance acts as a single API endpoint, and securely forwards API requests to running Team Servers and desktop clients. It distributes workload and maintains a balance between service availablity and data consistency.

Next steps

Tutorial

Read this tutorial and write your first AeroFS app!

The full API reference is available here.

API mailing list

Join our mailing list to be notified of API updates.

Feedback

Any comments about the AeroFS API? Send your ideas to api@aerofs.com.

Create your first AeroFS app

Welcome! In this article we will introduce everything you need to know to build a very basic AeroFS app. For complete API reference check out this document.

The mock API server

We have set up a mock API server at apiary.io so you can try out the API with no setup required! Try making a GET request (with your browser or with a command-line tool like cURL) to https://aerofs.apiary.io/api/v0.10/children/9f8e7d.

Note that this is only a mock server. It will let you experiment with the formatting of the API calls and responses, but you cannot modify any content on the server. The mock server also does not require any proof of authorization to make API calls, unlike a real AeroFS Appliance.

If you want to try out the mock server, skip to step 4. Otherwise, keep reading!

Step 1: Set up a Private Cloud instance

The AeroFS API is available in the AeroFS Private Cloud only. You need to set up a Private Cloud environment, which will be used as a sandbox for testing purposes.

A. Request a developer license
Request a license which is free for development purposes.
B. Set up the appliance
Once a license is issued, download and install the AeroFS Appliance. Check out this article for system requirements for Appliance setup. In the following text, we use host.name to represent the hostname of this appliance.
C. Set up a desktop client

A running desktop client or Team Server is needed for your app to access user content, and it is easier to inspect data using a client.

After creating the first user account in the above step, download the desktop client from the appliance and set it up using the user account. Do not install on a computer with production AeroFS installed, as it would overwrite the production installation.

If you want to start over, simply set up a new Private Cloud instance. Just remember to unlink and uninstall desktop clients and Team Servers cleanly before setting up a new instance, as these applications will be incompatible with new instances. Read more.

Step 2: Register an app

Go to http://host.name:8484/register_app to register your first app into the appliance. Set the name of the app "My First App" and the redirect URL http://blackhole. In the real world, the URL should be the address of your app. For testing, we use a non-existing URL to avoid the hassle of setting up a Web server.

Once the registration is done, the Web page shows you the Client ID and Client Secret of the new app, which are needed for Step 3. An example is shown in the screenshot to the right. You can revisit this page at http://host.name:8484/registered_apps at any time.

Step 3: Get an access token

This and later steps will become part of your app, written in a programming language that you prefer. In this tutorial, however, we use the command-line tool cURL to demonstrate raw message exchanges.

A. Ask the user to authorize your app

Your app should automatically send the user to the following URL so that the user can authorize the app to their AeroFS account:

https://host.name/authorize?response_type=code&redirect_uri=http://blackhole&client_id=30fd5241-02ea-46d5-ab07-f0aeba4164c3

For testing, replace the client_id argument in the above URL with the Client ID you obtained in Step 2, and visit this URL in your browser. Note that the redirect_uri argument must be identical to the redirect URL you entered in Step 2.

B. Obtain an access token

Once the user presses the Accept button on the above page, they will be directed to your app's redirect URL. An authorization code is included in the URL. Your app should use this code to exchange for an access token.

For testing, click the Accept button. Since we didn't provide a valid redirect URL, the browser will display this URL in the address bar and complain that the address is not found:

http://blackhole?code=67926e86a873492582cf68874f71a112

Then, use the code in the URL to request for an access token using this command:

$ curl -i -X POST https://host.name/auth/token \
    -d 'client_id=30fd5241-02ea-46d5-ab07-f0aeba4164c3' \
    -d 'client_secret=0212ff9a-febe-4eb2-96f0-424adb5aa47d' \
    -d 'redirect_uri=http://blackhole' \
    -d 'grant_type=authorization_code' \
    -d 'code=67926e86a873492582cf68874f71a112'

Remember to replace the code argument with the code in the URL displayed by your browser, and client_id and client_secret with the values you obtained in Step 2.

If the request is successful, you should expect the following JSON object in the response body:

{
   "access_token": "b383965fbb284c4fa95bebb3a5f392e8",
   "token_type": "bearer",
   "expires_in": 0,
   "scope": ""
}

As a security measure, the authorization code is valid only for a few seconds. If the request is not made in time, you may get "400 Bad Request" with an error description "the authorization code is invalid". In this case, simply run Step 3A again to obtain a new code.

The access_token you get from the successful response will be used for all subsequent API requests. The zero-valued expires_in field indicates that the token never expires until the user revokes the app from their accounts.

Step 4: List folders

To list children under the root AeroFS folder, call GET /children with no arguments:

$ curl -i https://host.name/api/v0.10/children \
    -H 'Authorization: Bearer b383965fbb284c4fa95bebb3a5f392e8'

The "/api/v0.10" string is a common prefix for all REST API calls. The "Authorization" header carries the access token. Remember to replace the string "b383..." with your own token obtained in Step 3B.

Important: if your appliance uses a self-signed SSL certificate, cURL will block your requests by default. For testing, you can use the cURL's --insecure flag. However, any app you write should be configured to trust the appliance's SSL certificate. Click here for more about app configuration.

The response body of a successful response is a Children object:

{
   "parent": "3293523a4ca93cd5bcc17d4c4a00946800000000000000000000000000000000",
   "folders": [],
   "files": []
}

The parent field is the identifier of the root folder. The folders and files fields are empty because we haven't created any files or folders. Otherwise, they should contain a list of Folder or File objects.

If no clients or Team Servers are running at the time the request is made, you would expect a "503 Service Unavailable" response.

Step 5: Upload files

A. Create a new file

An empty file must be created with POST /files before populating file content:

$ curl -i -X POST https://host.name/api/v0.10/files \
    -H 'Content-Type: application/json' \
    -d '{"parent": "3293523a4ca93cd5bcc17d4c4a00946800000000000000000000000000000000", "name": "hello.txt"}' \
    -H 'Authorization: Bearer b383965fbb284c4fa95bebb3a5f392e8'

The request body is specified in the -d option. Replace its parent field with the root folder ID you obtained in Step 4, to create a file "hello.txt" under your root AeroFS folder. Also replace the access token as before.

The response body of a success response is a File object:

{
   "id": "3293523a4ca93cd5bcc17d4c4a009468d1e675b41e8d4c309fc9796a899ee405",
   "name": "hello.txt"
   "last_modified": "2014-01-01T00:32:58Z",
   "size": 0,
   "mime_type": "text/plain",
}

The id field is the identifier of the newly created file.

B. Populate file content

First, create a file locally:

$ echo 'Hello, world!' > hello.upload.txt

Then, upload this file by calling PUT /files/{id}/content, with {id} being the identifier of the target file:

$ curl -i -X PUT https://host.name/api/v0.10/files/3293523a4ca93cd5bcc17d4c4a009468d1e675b41e8d4c309fc9796a899ee405/content \
    -T hello.upload.txt \
    -H 'Authorization: Bearer 845a1a4512164fc786da886f1320173a'

Replace "3293..." with the file ID obtained from Step 5A. Also replace the access token as before.

The server will return 200 with an empty body once the upload is successful.

Step 6: Download files

Download a file's content by calling GET /files/{id}/content with {id} being the file's identifier:

$ curl -i https://host.name/api/v0.10/files/3293523a4ca93cd5bcc17d4c4a009468d1e675b41e8d4c309fc9796a899ee405/content

Use the identifier obtained in Step 5A in the URL. Alternatively, call GET /children as demonstrated by Step 4, and retrieve file identifiers from the response.

There are options such as range requests and conditional requests for file downloading. Check out the API doc for advanced usage.

Next steps

We've covered the basic stuff for your AeroFS app. Skim through the API reference to see what else your app can do with the API.

Email api@aerofs.com for issues and other comments, or if you are interested in helping us build SDKs.

Once your app is ready to go, package and ship it!

Choose the right consistency policy

When an API request is made, the load balancer selects a Team Server to serve the request. If your organization does not use a Team Server, or if there is no Team Server available, a Desktop Client will be selected to serve the request.

If there are multiple computers that can serve a request, the load balancer's selection algorithm impacts the service availability and data consistency observed by the end user. For example, if a computer becomes unavailable after being used by the load balancer to serve a request, the load balancer may decide to use a different computer to serve the user's next request. If the two computers are not fully in sync, the two requests may return inconsistent results.

Your app can dictate how the load balancer selects computers. To deliver a satisfying user experience, it is important to understand your users' needs and pick the right policy for your app.

The default policy

By default, the load balancer uses the same computer for all the requests within an HTTP session between the app and the load balancer. A new computer is selected only if the originally selected computer becomes unreachable. This policy is suitable for most apps.

To apply the default policy, simply make sure HTTP cookies are enabled in your app.

Prefer availability over consistency

Under this policy, the load balancer may freely select different computers to serve different requests. This gives the system flexibility to choose the most available computers based on performance and load distribution, at the cost of potential inconsistency the end user may observe.

To use this policy, omit cookies when making requests. This effectively ends the HTTP session after each request.

Prefer consistency over availability

This policy doesn't allow the load balancer to change the selected computer in an HTTP session. An error will be returned if the selected computer becomes unavailable. This is the correct policy for an app which requires highly consistent behavior.

Enable cookies and specify Endpoint-Consistency: strict in the request headers to use this policy.

Note: this policy allows your app to control how consistency is maintained within an HTTP session, but not across sessions. Furthermore, your app cannot specify how the load balancer selects the first computer for a session. Thus, this policy implements session consistency. Learn more about consistency models in a distributed system.

Publish your app

Package it

Unlike traditional API models where all apps are registered with a single web service, AeroFS apps must be registered with individual AeroFS Private Cloud instances by the appliance administrators. Your app will therefore require some configuration for data that is different between AeroFS Private Cloud instances. Your app should accept four configuration values:

Client ID:
The unique identifier your app presents to the OAuth server
Client secret:
The password your app uses to authenticate with the OAuth server
Hostname:
The hostname the AeroFS Appliance
Browser certificate:
The SSL certificate of the AeroFS Appliance in x509 format. Your app should always use this certificate to verify the authenticity of the API endpoint.

When an appliance administrator registers an app, the AeroFS Appliance supplies the admin with a JSON data file that includes all the fields described above. To deliver a consistent user experience, all AeroFS apps should prompt the admin to upload this file when the admin configures the app.

Below is an example of the file content:

{
   "hostname": "host.name",
   "cert": "-----BEGIN CERTIFICATE-----\nMIIFKjC...",
   "client_id": "30fd5241-02ea-46d5-ab07-f0aeba4164c3",
   "client_secret": "0212ff9a-febe-4eb2-96f0-424adb5aa47d"
}

Publish it

As per our license agreement, you may use your app immediately for any internal usage.

If you'd like to publish your app for public distribution, drop us a line at api@aerofs.com with a brief description as well as a demo URL of your app. We will work with you to publish your app to our customers and partners.