CloudFS

Cloud storage APIs for developers

Sign Up

Bitcasa Drive

Cloud storage for your personal files

Sign Up

To facilitate rapid development, Bitcasa has set up a free CloudFS Prototype Plan in which you can build your app before taking it live. It gives you unlimited access to the full CloudFS feature set but is limited by capacity. When you are ready to deploy, you can upgrade to a higher capacity paid CloudFS plan that meets your needs.

To sign up for the Prototype plan:

1. Click the Sign Up button at the top-right of the home page or sign up at the CloudFS Plans page.

A choice of the Prototype plan and three grades of Paid plans appears.

cloudfs_plans

2. Click the Get Started button in the Prototype column and enter the developer username/email and password into the Sign Up dialog.

cloudfs_sign_up  

The email address also serves as your CloudFS Developer’s username.

Creating an App and Test End-user

Before starting work, you need to create the app you will build and at least one test test end-user. While developing your app, you call CloudFS APIs on behalf of this test end-user.

CloudFS walks you through this process.

When you clicked Sign Up, the “New Application” dialog appeared.

new_application_dlg  

1. Enter the Application Name and choose a type.

Any type is fine; choose the type of app that you intend to build. If you change your mind, just create another App.

When you click Next, it displays the “New Test Account” dialog.

new_test_account  

2. Enter a username/password for the test end-user.

Important: Don’t use the same email address as the one you used for your developer’s account.

3. Click Sign Up to complete the process.

The Developer’s Console appears, showing the URL of your API server at the top, your app(s), and your test user(s).

4-successful_process

Save the URL of your API server in a safe place. You will need it for all API requests.

OAuth2 Authentication

CloudFS uses OAuth2 to prevent unauthorized access to protected resources. You request access on behalf of an end-user by presenting the end-user’s access token. This access token incorporates information about your API server, your app, and the end-user for whom you are requesting access to resources.

To generate an access token for this test end-user:

1. Click the “Generate Token” button adjacent to a test end-user.

CloudFS asks for this end-user’s password as a security measure.

2. Enter the end-user’s password and click Generate.

CloudFS computes the access token and displays it below the test end-user’s username.

lori_access_token  

3. Save the access token in a safe place. You will need it as authorization in every HTTP request that you make for this end-user.

You are now ready to begin development! In the next section, we will call some CloudFS APIs on behalf of this end-user.

Using CloudFS APIs

You can use a number of programming tools to send requests to your API server; we will illustrate CloudFS using cURL. Another popular choice is the Chrome plug-in, Postman. The REST documentation includes both the raw (HTTP) form of each request and the corresponding cURL statements.

Creating a Folder

The Create Folder API creates a folder at any location in the end-user’s filesystem. This example does not pass a location, so it defaults to the root directory. See the Create Folder documentation for information about the request headers and parameters of this API.

This request uses the url of the API server and the Authorization header uses the access token for the test end-user.

curl https://jgw6pgwa16.cloudfs.io/v2/folders/?operation=create  \
-H 'Authorization: Bearer US2A.fd861df747c54e08a4e8e747307a9c30.S9h5uQqcj3hSbddLodbseLmhCMVcIsgo5AWy-gbFpQE' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'name=my_first_folder'

API Server Responses

If the request is successful, the API Server responds with a JSON object of this form:

{
	"error": null,
	"result": "This was a success."
}

Result is populated with a JSON object and error is null. Conversely, if the request failed, error contains the HTTP error code and a human-readable message.

Example Success Response

In this case, a successful response contains the metadata of the new folder.

HTTP/1.1 200 OK
Content-Type: application/json

{
	"result": {
	"items": [
	{
		"date_content_last_modified": 1431622116, 
		"name": "my_first_folder", 
		"parent_id": "", 
		"version": 1, 
		"application_data": {}, 
		"date_meta_last_modified": 1431622116, 
		"date_created": 1431622116, 
		"is_mirrored": false, 
		"type": "folder", 
		"id": "M9z1Y-SfRr-fqwXTsODMBQ"
	}]
    },
	"error": null
}

Listing the Contents of a Folder

The List Folder API lists the contents of a folder at any location in the filesystem. The location is passed as the Path parameter. If no location is passed, it lists the folders at the root. That’s where our one folder is, so we accept the default.

Here is the cURL:

curl https:jgw6pgwa16.cloudfs.io/v2/folders/ \
-H 'Authorization: Bearer US2A.fd861df747c54e08a4e8e747307a9c30.S9h5uQqcj3hSbddLodbseLmhCMVcIsgo5AWy-gbFpQE' \
-H 'Content-Type: application/x-www-form-urlencoded'  \
-H 'Accept: application/json'

Example Success Response

The API returns the metadata of the root folder and the metadata of all the items it contains. In this case, root contains only our “my_first_folder” folder so there is only one item.

HTTP/1.1 200 OK
Content-Type: application/json

{
	"error":null,

	"result": {
		"meta": {
		"date_content_last_modified": 1428963936, 
		"name": "root", 
		"parent_id": "", 
		"version": 1, 
		"application_data": {
			"_server": {"running_path_name": "/"}}, 
			"date_meta_last_modified": 1428963936, 
			"date_created": 1428963936, 
			"is_mirrored": false, 
			"type": "root", 
			"id": ""}, 
			"items":[
				{"date_content_last_modified": 1431622116, 
				"name": "my_first_folder", 
				"parent_id": "", 
				"version": 1, 
				"application_data": {
					"_server": {"relative_id_path": ""}}, 
					"date_meta_last_modified": 1431622116, 
					"date_created": 1431622116, 
					"is_mirrored": false, 
					"type": "folder", 
					"id": "M9z1Y-SfRr-fqwXTsODMBQ"
				}
			]
		}
	}
}

Creating an End-User for a Paid CloudFS Plan

Under the Prototype plan, you create end-users at the Developer’s Console, but when you upgrade to any Paid plan you create end-users programmatically. You use the Create Account API. You simply pass the username and password of the new end-user.

Here is some example cURL for the Create Account API:

curl -X POST https://<API Server>/v2/admin/cloudfs/customers/  \
-H 'Authorization : BCS <client_id>:<Bitcasa_authkey_signature>' \
-H 'Content-Type : application/x-www-form-urlencoded'   \
-H 'Date : <Datetime>'   \
-d 'username=<USERNAME>'  \
-d 'password=<PASSWORD>'

Notice that this Authorization header uses your app’s client_id and the Bitcasa AuthKey Signature instead of your access token. You can’t use your test end-user’s access token because it does not authorize you to call this API. After all, this call does not involve your Prototype end-user. This needs to be a signed HTTP request.

The <Bitcasa_authkey_signature> is a function of the client_id and client_secret of your app, your API server url, the new end-user’s credentials, and the current UTC timestamp. See the links in the Next Step for information on how to compute this function.

Creating an Access Token under a Paid Plan

To obtain an access token for an end-user under any Paid plan, use the OAuth2 Password Credentials Grant API. Here is some example cURL code:

curl https://<API Server>/v2/oauth2/token  \
-H 'Authorization: BCS <client_id>:<Bitcasa_authkey_signature>' \
-H 'Content-Type: application/x-www-form-urlencoded'  \
-H 'Date : <Datetime>'   \
-d 'grant_type=password'  \
-d 'username=<username>'   \
-d 'password=<password>'

This request must also be signed. Notice that this call passes the Paid end-user’s credentials as Form parameters. The result of a successful call is an access token that is valid for that user on any Paid plan.

The Next Step

You’re now ready to start building an app that uses CloudFS as your back-end solution! Here are some resources that will help you.

• Summaries of CloudFS APIs,

• Overview of the Authentication Process,

• Bitcasa Authkey Signature Documentation,

• Bitcasa Authkey Signature Tutorial.

If you have any questions, please contact CloudFS technical support.