Tiktalik Files is mostly compatible with the Amazon S3 service, as far as basic functionality goes. This means most S3 client libraries can be used with relative ease.
Our library of choice for the Python programming language is boto. This tutorial will guide you through basic operations you will need to perform as a developer.
Boto can be installed using the pip package manager:
$ pip install boto
If you'd rather install from source, see these instructions. Our recommendation is to install a stable version using pip.
To use Tiktalik Files, you need to create an S3Connection object:
from boto.s3.connection import S3Connection conn = S3Connection(<Login>, <Access key>, host="sds.tiktalik.com", is_secure=False)
You need to use your actual Tiktalik Files credentials, which can be found in the Files section in your Tiktalik Admin Panel.
For brevity, the other code examples will assume the connection object is already created.
All your files are stored in entities called Buckets. Bucket names are unique across Tiktalik Files. You create a Bucket once, then fill it with files.
bucket = conn.create_bucket("my-bucket", policy="authenticated-read")
This only needs to be done once. From this point the bucket "my-bucket" belongs to you, and nobody else (even you) can create a bucket with the same name.
It is recommended that you set access policy to "authenticated-read". This makes it impossible for anyone to list all the files stored in your buckets, which is usally what you want. Please refer to Tiktalik Files documentation for more information on Buckets and access policies.
Once you have created a bucket, you can store files in it. Each file is represented by a Key object. Keys belong to Buckets, and boto's object model reflects this relation.
Example of storing files in an existing bucket:
from boto.s3.key import Key from boto.s3.bucket import Bucket bucket = Bucket(conn, "my-bucket") # Create a new key. This doesn't upload anything yet. key = Key(bucket) # Set the key's path relative to the bucket. key.key = "test.txt" # Set the Content-Type that will be stored in the key's metadata key.content_type = "text/plain" # Upload the key's contents. Allow anyone to access this file. key.set_contents_from_string("This is a test.", policy="public-read")
From this point the file can be accessed directly using the URL http://my-bucket.sds.tiktalik.com/test.txt.
There are more methods to provide the file's contents. Most notable are:
More details can be found in boto's documentation for Key.
Please note that if you don't specify the key's access policy, it will be inherited from the bucket's policy. We wanted the file to be publicly readable, thus the usage of "public-read".
If we wanted the have control over who gains access to the resource, we'd pass "authenticated-read" as policy.
From a web developer's point of view, the easiest method to control access to objects stored in the Tiktalik Files system is to:
Generating authenticated links is performed server-side, since this is the place where one can safely store Tiktalik Files credentials. The following code generates a link that allows access to test.txt for 15 minutes.
key = Key(bucket) key.key = "test.txt" # Pass number of seconds we want the URL to be valid url = key.generate_url(15 * 60)
This URL can be passed to the user's browser (ie. in an img tag). The URL is valid only for the next 15 minutes, which, among other things, protects from hot-linking files.
Tiktalik Files allows keys to be deleted only by the bucket's owner. This example code shows how to remove a file:
key = Key(bucket) key.key = "test.txt" key.delete()