Home Advanced Archive API Archive Tutorial

Archive

The Archive function provides a general purpose data storage facility paid with usage tokens. You can Look at an archive entry by its hash, which lets you read the content but not change it. You can also Touch an entry directly by its location, which lets you change the content with the Write operation. Writing new content costs 1 usage token per 16 bytes of encrypted data added to the database, or yields a 1 token refund per 16 bytes reduced. (There can be a few bytes of overhead added in the encryption process.)

Before you can write an entry, you must first Buy its location for 1 usage token. This helps prevent accidentally writing to an incorrect location. You may then write arbitrary content into the purchased location. Later, if you want to Sell the location back to receive a 1 token refund, you must first clear it out by writing null content into it.

All content is encrypted in the database using a key derived from the archive location.

Example API Call

Here is a url which writes the string "abc" into archive location c80481226973dfec6dc06c8dfe8a5b1c, paying for the storage from usage location 29013fc66a653f6765151dd352675d0f. Note that in order for this to work, you must have already bought the archive location.

?function=archive&action=write
	&usage=29013fc66a653f6765151dd352675d0f
	&loc=c80481226973dfec6dc06c8dfe8a5b1c
	&content=abc

(The url is broken up across lines for clarity. In practice you would keep the entire url on a single line.)

You may use content with multiple lines or arbitrary binary characters. All you have to do is "uri_escape" the content to convert it into a form suitable for use in a url. (For you perl programmers, see the URI::Escape module.) For example, this multi-line string:

first/line
second/line

would be encoded by uri_escape as:

first%2Fline%0Asecond%2Fline%0A

For better support of very large content, there will soon be an API call which is compatible with the HTTP "file upload" protocol. But for now, the simple "write" operation should suffice just fine for most purposes (even with large content).

Archive Operations

Here we describe the API (application programming interface) for the Archive. The operations are Buy, Sell, Touch, Look, and Write.

Buy a location in the archive. This costs 1 usage token. The location must currently be vacant (not bought) in order to buy it. The input is:

If the Buy operation succeeds, you will see the following keys in the result:

If the operation fails, the status will be fail, and the reason for the failure will be indicated with any keys below which apply:

Sell a location in the archive. This refunds 1 usage token. The content at the location must currently be empty (null) in order to sell the location. The input is:

If the Sell operation succeeds, you will see the following keys in the result:

If the operation fails, the status will be fail, and the reason for the failure will be indicated with any keys below which apply:

Touch a location in the archive. The input is:

If the Touch operation succeeds, you will see the following keys in the result:

If the operation fails, the status will be fail, and the reason for the failure will be indicated with any keys below which apply:

Look at a location in the archive by its hash. The input is:

If the Look operation succeeds, you will see the following keys in the result:

If the operation fails, the status will be fail, and the reason for the failure will be indicated with any keys below which apply:

Write content into the archive. The system first encrypts the content using a key derived from the location. This may impose an overhead of a few bytes. It then compares the new encrypted length with the length of any existing content at this location, and determines how many bytes would be added or subtracted on net if it were to write out the new content. It then charges 1 usage token per 16 bytes added, or refunds 1 usage token per 16 bytes subtracted.

The input is:

If the Write operation succeeds, you will see the following keys in the result:

NOTE: the "content" key supplied in the input is not echoed back in the result, because that would just be a waste of time and bandwidth.

If the operation fails, the status will be fail, and the reason for the failure will be indicated with any keys below which apply: