This add-on is operated by CloudRail

Integrate APIs 10x faster & never worry about breaking integrations again.

Last updated 25 January 2017

CloudRail is an add-on that lets developers integrate APIs ten times faster and never worry about breaking integrations again.

Adding CloudRail to your application will enable you to integrate many APIs in little time through consistent and easy-to-use interfaces that bundle similar services. CloudRail facilitates OAuth, transparently handles changing APIs for you and shows you statistics about API usage. CloudRail sits as a library right on top of your software and communicates directly with the services. No data ever passes through a CloudRail server so no overhead, no single point of failure and no privacy concerns.

CloudRail comes with libraries for Java, Node.js, Android and iOS (Objective-C / Swift).

Provisioning the add-on

CloudRail can be attached to a Heroku application via the CLI:

$ heroku addons:create cloudrail
-----> Adding cloudrail to sharp-mountain-4005... done, v18 (free)

Once CloudRail has been added a CLOUDRAIL_LICENSE_KEY setting will be available in the app configuration and will contain the license key for your CloudRail app. This can be confirmed using the heroku config:get command.

$ heroku config:get CLOUDRAIL_LICENSE_KEY
5834196eb...

After installing CloudRail the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add CloudRail’s license key to your .env file.

$ heroku config:get CLOUDRAIL_LICENSE_KEY -s  >> .env

For more information, see the Heroku Local article.

Service setup

CloudRail can be used through one if its SDKs which needs to be installed first. The following sections outlines the most common installation method and an example for each platform. Alternative installation methods and detailed usage is explained in the CloudRail Documentation.

Java

Find and install the newest version into your project via Maven Central.

Then you can use code like the following:

import com.cloudrail.si.CloudRail;
import com.cloudrail.si.interfaces.CloudStorage;
import com.cloudrail.si.services.Box;
import com.cloudrail.si.services.OneDrive;
import com.cloudrail.si.services.GoogleDrive;
import com.cloudrail.si.services.Dropbox;

CloudRail.setAppKey(System.getenv("CLOUDRAIL_LICENSE_KEY"));

// CloudStorage cs = new Box(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
// CloudStorage cs = new OneDrive(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
// CloudStorage cs = new GoogleDrive(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
CloudStorage cs = new Dropbox(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
new Thread() {
    @Override
    public void run() {
        cs.createFolder("/TestFolder");
        InputStream stream = null;
        try {
            stream = getClass().getResourceAsStream("Data.csv");
            long size = new File(getClass().getResource("Data.csv").toURI()).length();
            cs.upload("/TestFolder/Data.csv", stream, size, false);
        } catch (Exception e) {
            // TODO: handle error
        } finally {
            // TODO: close stream
        }
    }
}.start();

Above example prompts the user to login to their cloud storage account (this is implicitly done on the first method call). Then, it creates a new folder in that account and uploads a file to it. As you can see, since all services implement the same interface they can be used interchangeably.

Node.js

Install the newest version into your project via

$ cd YOUR_PROJECT_FOLDER
$ npm install cloudrail-si --save

This installs CloudRail and adds it as a dependency to your package.json file. Then you can use code like the following:

const cloudrail = require("cloudrail-si");
cloudrail.Settings.setKey(process.env.CLOUDRAIL_LICENSE_KEY);

// let cs = new cloudrail.services.Box(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
// let cs = new cloudrail.services.OneDrive(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
// let cs = new cloudrail.services.GoogleDrive(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");
let cs = new cloudrail.services.Dropbox(redirectReceiver, "[clientIdentifier]", "[clientSecret]", "[redirectUri]", "[state]");

cs.createFolder("/TestFolder", (err) => { // <---
    if (err) throw err;
    let fileStream = fs.createReadStream("UserData.csv");
    let size = fs.statSync("UserData.csv").size;
    cs.upload("/TestFolder/Data.csv", fileStream, size, false, (err) => { // <---
        if (err) throw err;
        console.log("Upload successfully finished");
    });
});

Other platforms

Android and iOS SDKs are available as well, though they obviously do not run on Heroku directly. CloudRail is cross-platform, so if you want to use it on any of those platforms, e.g. for your client applications, you can find instructions in the CloudRail Documentation.

Dashboard

The CloudRail dashboard allows you to see the health status of your API integrations, usage statistics and more.

The dashboard can be accessed via the CLI:

$ heroku addons:open cloudrail
Opening cloudrail for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select CloudRail from the Add-ons menu.

Questions?

Get in touch at any time by emailing us: support@cloudrail.com

or

Tag a question with ‘cloudrail’ on StackOverflow

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade cloudrail:newplan
-----> Upgrading cloudrail:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: cloudrail:newplan

Removing the add-on

CloudRail can be removed via the CLI.

$ heroku addons:destroy cloudrail
-----> Removing cloudrail from sharp-mountain-4005... done, v20 (free)