<commit_before># Introduction to Long Access API v1

## Getting started

Visit [stage.longaccess.com](http://stage.longaccess.com/) and create a new user. You will need this user's credentials to test your client. 

Verify user (users are identified by their email) using the API:

    curl -u email:password \
    --dump-header - \
    -H "Accept: application/json" \
    http://stage.longaccess.com/api/v1/account/

While at it, you should also create at least one DataCapsule. Use the following (dummy) credit card (provided by braintree sandbox):

    Credit Card Number: 4111111111111111
    CVV: 111 
    Expiration Date: 11/2015

Verify that the DataCapsule was created using the API:

    curl -u email:password \
    --dump-header - \
    -H "Accept: application/json" \
    http://stage.longaccess.com/api/v1/capsule/
   
## Preparing the archive.

There are two steps here, preparing the archive and encrypting the archive. There are many options for each step which will be detailed in the next two sections. However the following is a quick, recommended, example:

* The user selects the files to add
* The client creates a ZIP archive with the files
* It generates a 256 bit random key
* It encrypts the archive with AES in CTR mode

### Encrypting the archive

For each archive, the client will have to generate a new random key and encrypt the archive with it before uploading it to the service.

By default the archive should be encrypted with a new random 256 bit key using [AES in CTR mode][] with an IV of zero. The key should only be used for the encryption of one archive and never be reused again.

Also, using a mature cryptography library, like [openssl][], [cryptlib][] or [BouncyCastle][] is highly recommended.

 [AES in CTR mode]: http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29
 [openssl]: https://www.openssl.org/
 [BouncyCastle]: http://bouncycastle.org/
 [cryptlib]: http://www.cs.auckland.ac.nz/~pgut001/cryptlib/
 [ADF]: adf.md 

## Uploading the archive.

Briefly the steps for the archive upload are (more details follow):

* the user selects which data capsule to upload to
* she inputs a title and free text description for the archive
* the client initializes an upload 
* it transmits the archive
* it requests confirmation of successful completion

### Preparation

So, after preparing the encrypted archive (just *archive* from now on) the user must upload it to the DataCapsule. Before actually uploading the client should use the API to verify user, get available DataCapsules, and present the user with the ones that have enough free space to hold the archive.

A `title` and `description` should also be provided by the user. This information will make it easier to navigate a user's list of archives in the future, and it's the only piece of information we (Long Access) have about the nature of the data stored (and can present to the user in the future).

### Initialization

Then the client initiates the upload using the `/upload/` call, providing the destination capsule and archive description. The API responds with all the available information about the transmission of the archive. Example of archive upload initiation request:
    
    curl -u email:password \
    --dump-header - \
    -H "Content-Type: application/json" \
    -X POST \
    --data '{\
    		"title": "test", \
    		"description": "My awesome photos", \
    		"capsule": "/api/v1/capsule/1/", \
    		"size": 10512,\
    		"checksum": "md5:d85d8251bd93decb7396e767700acb9f"\
    }' \
    http://stage.longaccess.com/api/v1/upload/

And response:
<commit_msg>Update intro.md<commit_after># Introduction to Long Access API v1

## Getting started

Visit [stage.longaccess.com](http://stage.longaccess.com/) and create a new user. You will need this user's credentials to test your client. 

Verify user (users are identified by their email) using the API:

    curl -u email:password \
    --dump-header - \
    -H "Accept: application/json" \
    http://stage.longaccess.com/api/v1/account/

While at it, you should also create at least one DataCapsule. Use the following (dummy) credit card (provided by braintree sandbox):

    Credit Card Number: 4111111111111111
    CVV: 111 
    Expiration Date: 11/2015

Verify that the DataCapsule was created using the API:

    curl -u email:password \
    --dump-header - \
    -H "Accept: application/json" \
    http://stage.longaccess.com/api/v1/capsule/
   
## Preparing the archive.

There are two steps here, preparing the archive and encrypting the archive. There are many options for each step which will be detailed in the next two sections. However the following is a quick, recommended, example:

* The user selects the files to add
* The client creates a ZIP archive with the files
* It generates a 256 bit random key
* It encrypts the archive with AES in CTR mode

### Encrypting the archive

For each archive, the client will have to generate a new random key and encrypt the archive with it before uploading it to the service.

By default the archive should be encrypted with a new random 256 bit key using [AES in CTR mode][] with an IV of zero. The key should only be used for the encryption of one archive and never be reused again.

Also, using a mature cryptography library, like [openssl][], [cryptlib][] or [BouncyCastle][] is highly recommended.

 [AES in CTR mode]: http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29
 [openssl]: https://www.openssl.org/
 [BouncyCastle]: http://bouncycastle.org/
 [cryptlib]: http://www.cs.auckland.ac.nz/~pgut001/cryptlib/
 [ADF]: adf.md 

## Uploading the archive.

Briefly the steps for the archive upload are (more details follow):

* the user selects which data capsule to upload to
* she inputs a title and free text description for the archive
* the client initializes an upload 
* it transmits the archive
* it requests confirmation of successful completion

### Preparation

So, after preparing the encrypted archive (just *archive* from now on) the user must upload it to a DataCapsule. Before actually uploading the client should use the API to verify user, get available DataCapsules, and present the user with the ones that have enough free space to hold the archive.

A `title` and `description` should also be provided by the user. This information will make it easier to navigate a user's list of archives in the future, and it's the only piece of information we (Long Access) have about the nature of the data stored (and can present to the user in the future).

### Initialization

Then the client initiates the upload using the `/upload/` call, providing the destination capsule and archive description. The API responds with all the available information about the transmission of the archive. Example of archive upload initiation request:
    
    curl -u email:password \
    --dump-header - \
    -H "Content-Type: application/json" \
    -X POST \
    --data '{\
    		"title": "test", \
    		"description": "My awesome photos", \
    		"capsule": "/api/v1/capsule/1/", \
    		"size": 10512,\
    		"checksum": "md5:d85d8251bd93decb7396e767700acb9f"\
    }' \
    http://stage.longaccess.com/api/v1/upload/

And response:

{'fraction_non_alphanumeric': 0.08033738938053098, 'fraction_numerical': 0.019081858407079644, 'mean_word_length': 3.6335682254964765, 'pattern_counts': {'":': 10, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '564623', 'n_tokens_mistral': 2160, 'n_tokens_neox': 1975, 'n_words': 953}