Getting started

With the expressFlow API you can easily integrate complex file-processing tasks into your applications - just by sending simple HTTP requests to the expressFlow REST API.
The fundamental principle of the expressFlow REST API is: Everything is in the Cloud. This principle radically changes the performance and the integration complexity of the API. You just need to send a link referring to the resource you want to process, and expressFlow does the REST for you ;-)

First of all: You need to create an API Key.
Check out your API Key and remember your Secret!
You need to provide these two with every API call.

Let's see, how this works:
To encrypt a file, you just need to send a link referring to the file you want to encrypt, the Content-Length and the MIME-Type. Wrap these three parameters into a JSON request and send them via a HTTP POST to https://www.expressflow.com/api/encrypt/.
expressFlow encrypts the resource and returns a link referring to the encrypted file and a link referring to the used keys. That's it. No resources were used in your application (like for example a mobile device).

To decrypt the file, you just need to additionally provide the link referring to the key. But this is optional - expressFlow stores the key for you safely, if you want.
It's up to you.


General Notes

SSL
expressFlow enforces SSL on all REST API calls.

Encoding
Every String passed to and from expressFlow needs to be UTF-8 encoded.


Authentication

All API calls need to authenticate by providing the API Key and the Secret in the Headers.
You can create your credentials in My API.

Architecture Flow

API Call Flow

This call flow executes the sequential API calls of a successfull encryption and decryption traversal from your application by calling the expressFlow API.
As you can see the API adheres to the following principles:

  • Full control over your keys (GET and DELETE)
  • Keep keys PRIVATE!
  • Store encrypted files in the cloud
  • En- and Decryption logic is performed in the cloud.

To sum it up: The API was designed to act like a remote control of the expressFlow encryption engine. No computing power of your mobile device is consumed for encryption or decryption functionality.

Overview

The expressFlow Encrypt API operates 100% cloud-enabled. That means that you do not need to upload, PUT or POST the file you want to encrypt to the expressFlow Encrypt API.
You just need to send over the link referring to the resource you want to encrypt. expressFlow does all the rest for you.
Let's see, how this works:

HTTP POST

To encrypt a file with expressFlow you need to send an HTTP POST request to

https://www.expressflow.com/api/encrypt

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.
  • Content-Length: Enables expressFlow to verify that everything is processed correctly.
  • Content-Type: application/json - all other types are rejected.

The body of the request must be a JSON with the following attributes:

{
 url: The URL referring to the resource you want to encrypt,
 name: The name of the resource,
 mimetype: The MIME - Type of the resource
}


Client Sample

Let's start with building a sample JSON request. That is rather simple:
Just provide the MIME type, the name and the URL.
Note: The URL MUST be provided url-encoded and in UTF-8 format. All other formats will be rejected by the expressFlow Encrypt API.

JSON Sample Request:
{
 "mimetype":"image%2Fpng",
 "name":"site.png",
 "url":"https%3A%2F%2Fdl.dropbox.com%2Fu%2F339812%2FexpressFlow%2Fsite.png"
}

Let's see how this JSON can be sent to the expressFlow Encrypt API using plain Java.

Java client sample:
import java.io.OutputStream;
import java.io.PrintWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import org.json.JSONObject;

JSONObject j = new JSONObject();
            j.put("mimetype", URLEncoder.encode("image/png", "UTF-8"));
            j.put("name", "site.png");
            j.put("url", URLEncoder.encode("https://dl.dropbox.com/u/339812/expressFlow/site.png", "UTF-8"));

            URL url = new URL("https://www.expressflow.com/api/encrypt/");
            HttpURLConnection request = (HttpURLConnection) url
                    .openConnection();
            request.setDoOutput(true);
            request.addRequestProperty("APIKey", "YOUR_API_KEY");
            request.addRequestProperty("Secret", "YOUR_API_SECRET");
            request.addRequestProperty("Content-Length", Integer.toString(j.length()));
            request.addRequestProperty("Content-Type", "application/json");
            request.setRequestMethod("POST");
            OutputStream output = request.getOutputStream();
            PrintWriter writer = new PrintWriter(output);
            writer.print(j);
            writer.close();

This sample basically builds up the JSON wrapping all required parameters and sends it over the wire using the HTTP POST request.
That's all. With this very basic code we encrypted a resource stored somewhere in the cloud.

Overview

The expressFlow Decrypt API operates 100% cloud-enabled. That means that you do not need to upload, PUT or POST the file you want to decrypt to the expressFlow Decrypt API.
You just need to send over the link referring to the encrypted resource you want to decrypt. expressFlow does all the rest for you.
Let's see, how this works:

  1. Prepare decryption by sending a HTTP POST to
    https://www.expressflow.com/api/decrypt
  2. Receive response containing the endpoint to decrypt
  3. HTTP POST the key to the previously received decryption endpoint

Ok basically that means that we need to perform one further step to decrypt.
Let's start with the Preparation call:

Preparation HTTP POST

To decrypt a file with expressFlow you need to send an HTTP POST request to

https://www.expressflow.com/api/decrypt

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.
  • Content-Length: Enables expressFlow to verify that everything is processed correctly.
  • Content-Type: application/json - all other types are rejected.

The body of the request must be a JSON with the following attributes:

{
 url: The URL referring to the resource you want to decrypt,
 name: The name of the resource,
}


Client Sample

Let's start with building a sample JSON request. That is rather simple:
Just provide the name and the URL.
Note: The URL MUST be provided url-encoded and in UTF-8 format. All other formats will be rejected by the expressFlow Encrypt API.

JSON Sample Request:
{
 "name":"site.png.aes",
 "url":"https%3A%2F%2Fdl.dropbox.com%2Fu%2F339812%2FexpressFlow%2Fsite.png.aes"
}

Let's see how this JSON can be sent to the expressFlow Decrypt API using plain Java.

Java client sample:
import java.io.OutputStream;
import java.io.PrintWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import org.json.JSONObject;

JSONObject j = new JSONObject();
            j.put("name", "site.png.aes");
            j.put("url", URLEncoder.encode("https://dl.dropbox.com/u/339812/expressFlow/site.png.aes", "UTF-8"));

            URL url = new URL("https://www.expressflow.com/api/decrypt/");
            HttpURLConnection request = (HttpURLConnection) url
                    .openConnection();
            request.setDoOutput(true);
            request.addRequestProperty("APIKey", "YOUR_API_KEY");
            request.addRequestProperty("Secret", "YOUR_SECRET");
            request.addRequestProperty("Content-Length", Integer.toString(j.length()));
           	request.addRequestProperty("Content-Type", "application/json");
           	request.setRequestMethod("POST");
            OutputStream output = request.getOutputStream();
            PrintWriter writer = new PrintWriter(output);
            writer.print(j);
            writer.close();

This sample basically builds up the JSON wrapping all required parameters and sends it over the wire using the HTTP POST request.
That's all.

JSON Sample Response:
{
 "decrypt_url":"https://expressflow-api.appspot.com/api/decrypt/key?keyId=1s2f8l...",
 "keyId":"1s2f8lpssbjgdhoqt18cnoqsua35au7p1hlma5co33ggkqm7vjpl"
}

This response contains the endpoint, where you can now decrypt the file. Just POST the previously retrieved key to this URL, and expressFlow decrypts your file.
Let's see how this works.

Decryption HTTP POST

To decrypt your prepared file with expressFlow you need to send an HTTP POST request to the previously received decryption endpoint.
In our example response, this was:

https://expressflow-api.appspot.com/api/decrypt/key?keyId=1s2f8l...

Info

This architecture scales!
Just in case you are wondering: You receive the server instance, deployed in the cloud that is able to decrypt your file. Our architectre adheres to the principle of data locality. With our API you dynamically receive the exact instances, that process your data.

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.

The body of the request must be the key file retrieved previously.

Overview

With the expressFlow File API you have full access to the processed ressources (both: encrypted and decrypted). Reduced to the minimum, the expressFlow File API works in the following steps:

  1. Encrypt or Decrypt a resource with the use of the expressFlow Encrypt or Decrypt API
  2. GET the encrypted or decrypted resource with the expressFlow File API
  3. Store the retrieved resource in your application (for encrypted ressources: store them in the Cloud)
  4. DELETE the encrypted or decrypted resource with the expressFlow File API

To sum it up: Process your ressource BEFORE you GET or DELETE it with the expressFlow File API.

HTTP GET

You encrypted a resource by sending a valid request to the expressFlow encrypt endpoint. The response JSON contains an attribute: encrypted_blob_url. This is the reference for the File endpoint.
The File endpoint is available at:

https://expressflow-api.appspot.com/file

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.

Requests to this endpoint must contain the following parameters:

  • fileId: Uniquely identifies the encrypted resource.

Sending a plain HTTP GET request with your valid APIKey and the matching Secret in the headers and a valid fileId as parameter returns the encrypted file:

HTTP GET Sample

GET https://expressflow-api.appspot.com/file?fileId={YOUR_FILE_ID}
APIKey: YOUR_API_KEY
Secret: YOUR_SECRET


HTTP DELETE

The encrypted resource resides at the expressFlow servers as long as you delete it. We strongly recommend that you store the encrypted resource savely in the cloud storage platform of your choice and then delete this encrypted blob from expressFlow.

To delete the encrypted resource permanently from the expressFlow servers you need to send a HTTP DELETE request with exactly the same parameters as the previously described HTTP GET:

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.

Requests to this endpoint must contain the following parameters:

  • fileId: Uniquely identifies the encrypted resource.

Sending a plain HTTP DELETE request with your valid APIKey and the matching Secret in the headers and a valid fileId as parameter deletes the encrypted file permanently.

Danger zone

Sending this request deletes the resource PERMANENTLY.
This request is NOT idempotent. Once you sent the request, the resource is deleted. Just be sure to store the resource BEFORE you delete it from the expressFlow servers.

HTTP DELETE Sample

DELETE https://expressflow-api.appspot.com/file?fileId={YOUR_FILE_ID}
APIKey: YOUR_API_KEY
Secret: YOUR_SECRET

Overview

With the expressFlow Key API you have full access to the key used for the encryption or decryption of your resources. Reduced to the minimum, the expressFlow Key API works in the following steps:

  1. Encrypt or Decrypt a resource with the use of the expressFlow Encrypt or Decrypt API
  2. GET the key used for encryption or decryption with the expressFlow Key API
  3. Store the retrieved key in your application (DO NOT store them in the Cloud)
  4. DELETE the key with the expressFlow Key API

To sum it up: Process your ressource BEFORE you GET or DELETE the used keys with the expressFlow Key API.

HTTP GET

You encrypted a resource by sending a valid request to the expressFlow encrypt endpoint. The response JSON contains an attribute: key_url. This is the reference for the Key endpoint.
The Key endpoint is available at:

https://expressflow-api.appspot.com/key

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.

Requests to this endpoint must contain the following parameters:

  • keyId: Uniquely identifies the key.

Sending a plain HTTP GET request with your valid APIKey and the matching Secret in the headers and a valid keyId as parameter returns the key:

HTTP GET Sample

GET https://expressflow-api.appspot.com/key?keyId={YOUR_KEY_ID}
APIKey: YOUR_API_KEY
Secret: YOUR_SECRET


HTTP DELETE

The key resides at the expressFlow servers as long as you delete it. We strongly recommend that you store the key savely in your local application storage before deleting it from expressFlow.

To delete the key permanently from the expressFlow servers you need to send a HTTP DELETE request with exactly the same parameters as the previously described HTTP GET:

Requests to this endpoint must contain the following headers:

  • APIKey: This key uniquely identifies each requester.
  • Secret: The matching secret to authenticate API access.

Requests to this endpoint must contain the following parameters:

  • keyId: Uniquely identifies the key.

Sending a plain HTTP DELETE request with your valid APIKey and the matching Secret in the headers and a valid keyId as parameter deletes the key permanently.

Danger zone

Sending this request deletes the key PERMANENTLY.
This request is NOT idempotent. Once you sent the request, the key is deleted. Just be sure to store the key BEFORE you delete it from the expressFlow servers.

HTTP DELETE Sample

DELETE https://expressflow-api.appspot.com/key?keyId={YOUR_KEY_ID}
APIKey: YOUR_API_KEY
Secret: YOUR_SECRET

Prerequisites

We love Dropbox and how this service enables us to have our documents available everywhere at every time. To enable web developers to integrate Dropbox more easily into their web apps, Dropbox published the Dropbox chooser recently.
This is a great component to enable visitors of your website to directly connect content stored in their personal dropbox accounts with your web app. The only thing you - as a web developer - need to do is to integrate a very basic JavaScript script - and it works.

We here at expressFlow think this is a cool idea - but an even cooler idea is to secure this component by encrypting all your stuff in your dropbox. Simply by the use of the Dropbox chooser. Would be nice, right?
Well - it's far easier than you think with our completely new web encrypter endpoint.

This new endpoint enables you to use all of the well known features of expressFlow - encrypting all your files with military strengh AES algorithms - by simply adding some very basic JavaScript code to your website.
Let's see, how this works.

First: Set up your domain

In the API console you can enter your domain. After you entered your domain name you receive the domain secret.

Domain Setup
After you setup your domain and stored your domain secret, you can make requests to the web-encrypted endpoint.

Second: Integrate the Dropbox chooser

To get started with the Dropbox Chooser we strongly recommend reading the Dropbox chooser docs. It's really easy to get your Dropbox chooser up and running, so this should not be a very time-consuming task.
To complete this sample you need to create an Dropbox app and already know how to integrate it into your web application.

Ok, so basically you need to integrate the Dropbox chooser into your website like the following example:

Click the Dropbox chooser

Security info

expressFlow will never gain FULL access to your Dropbox account. Basically it:
  1. loads the file from your Dropbox
  2. encrypts it with a very strong AES algorithm
  3. makes the encrypted file available to you

Name:

When you chose a file, you get a link to this file:

Be sure to check Direct link as the link type for your Dropbox chooser to enable expressFlow to directly encrypt your files from your Dropbox.

OK - that was not too hard, right?
We are ready for encryption! Let's go.

Encrypt it!

After you choose the file in your Dropbox you receive a link to the ressource. This link simply has to be passed to the expressFlow API to encrypt it:



Sending JSON to expressFlow API.


And now: Decrypt it!



File table:
# Type File Link