Developer Quick Start Guide

Learn how to get started with IPFS through Filebase with the AWS SDK for JavaScript, IPFS CLI tool, and the AWS CLI tool.

Filebase supports uploading and managing content on IPFS through our S3-compatible API or the IPFS pinning service API, creating a wide variety of workflows for developers to incorporate into their projects and workflows.

This quick start guide will cover some of the most common utilizations of Filebase in developer workflows, including using the AWS SDK for JavaScript, the IPFS CLI tool, and AWS CLI.

AWS SDK for JavaScript

AWS SDKs (software development kits) help simplify coding and application development by supporting and providing code objects for use with S3-compatible services. There are a variety of different AWS SDKs, each for a different coding language. This guide covers AWS SDK - JavaScript.

The AWS SDK for JavaScript supports three runtimes:

• JavaScript

• Node.js

• React Native for mobile development

AWS SDK - JavaScript also supports cross-runtime. Cross-runtime is a service client package that can be run on browsers, Node.js, and React-Native without needing any change to the code.

Prerequisites:

• Download and install npm in your environment if using the CLI.

• Download and install the AWS SDK for Javascript.

• Sign up for a free Filebase account.

• Have your Filebase Access and Secret Keys. Learn how to view your access keys here.

Declare the S3 Client

The following code example defines the S3 client and does not return any output. Replace the following values in the code to match your configuration:

• accessKeyId: Your Filebase Access Key

• secretAccessKey: Your Filebase Secret Key

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  apiVersion: '2006-03-01',
  accessKeyId: 'Filebase-Access-Key',
  secretAccessKey: 'Filebase-Secret-Key',
  endpoint: 'https://s3.filebase.com',
  region: 'us-east-1',
  s3ForcePathStyle: true
});

Retrieving Buckets

The following code example returns a list of buckets under your Filebase account. Replace the following values in the code to match your configuration:

• accessKeyId: Your Filebase Access Key

• secretAccessKey: Your Filebase Secret Key

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  apiVersion: '2006-03-01',
  accessKeyId: 'Filebase-Access-Key',
  secretAccessKey: 'Filebase-Secret-Key',
  endpoint: 'https://s3.filebase.com',
  region: 'us-east-1',
  s3ForcePathStyle: true
});

s3.listBuckets(function (err, data) {
  if (err) {
    console.log("Error when listing buckets", err);
  } else {
    console.log("Success when listing buckets", data);
  }
});

Creating a Bucket

The following code example creates a new Filebase bucket. Replace the following values in the code to match your configuration:

• accessKeyId: Your Filebase Access Key

• secretAccessKey: Your Filebase Secret Key

• Bucket: Your Filebase Bucket Name To Be Created

Bucket names must be unique across all Filebase users, be between 3 and 63 characters long, and can contain only lowercase characters, numbers, and dashes.

Buckets created through this method will be automatically created on the IPFS network.

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  apiVersion: '2006-03-01',
  accessKeyId: 'Filebase-Access-Key',
  secretAccessKey: 'Filebase-Secret-Key',
  endpoint: 'https://s3.filebase.com',
  region: 'us-east-1',
  s3ForcePathStyle: true
});

const params = {
    Bucket: "New-Filebase-Bucket"
}

s3.createBucket(params, (err, data)=>{
    if(err){
        console.log(err)
    } else {
        console.log("Bucket created", data)
    }
})

Listing Files in a Bucket

The following code example returns a list of objects in the bucket name provided. Replace the following values in the code to match your configuration:

• accessKeyId: Your Filebase Access Key

• secretAccessKey: Your Filebase Secret Key

• Bucket: Your Filebase Bucket Name

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  apiVersion: '2006-03-01',
  accessKeyId: 'Filebase-Access-Key',
  secretAccessKey: 'Filebase-Secret-Key',
  endpoint: 'https://s3.filebase.com',
  region: 'us-east-1',
  s3ForcePathStyle: true
});

const params = {
  Bucket: "filebase-bucket",
  MaxKeys: 20
};

s3.listObjectsV2(params, function (err, data) {
  if (err) {
    console.log("Error when listing objects", err);
  } else {
    console.log("Success when listing objects", data);
  }
});

Uploading Objects

The following code example uploads an object to the bucket name provided. Replace the following values in the code to match your configuration:

• accessKeyId: Your Filebase Access Key

• secretAccessKey: Your Filebase Secret Key

• Bucket: Your Filebase Bucket Name

• Key: The Local Path To The Object To Be Uploaded

• Content Type: The Type of Object Being Uploaded

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  apiVersion: '2006-03-01',
  accessKeyId: 'Filebase-Access-Key',
  secretAccessKey: 'Filebase-Secret-Key',
  endpoint: 'https://s3.filebase.com',
  region: 'us-east-1',
  s3ForcePathStyle: true
});

const params = {
  Bucket: 'filebase-bucket',
  Key: '/path/to/file/filename.png',
  ContentType: 'image/png',
  Body: myPictureFile,
  ACL: 'public-read',
};

const request = s3.putObject(params);
request.send();

Returning The Object’s IPFS CID Once Uploaded

This example uses the AWS SDK v2. For an example using the AWS SDK v3, please see here.

To return an object’s IPFS CID once it has been uploaded, you will need to return the x-amz-meta-cid header. The following code example uploads an IPFS file to the bucket name provided and returns the IPFS CID. Replace the following values in the code to match your configuration:

• accessKeyId: Filebase Access Key

• secretAccessKey: Filebase Secret Key

• Bucket: Your Filebase Bucket Name

• Key: The Local Path To The Object To Be Uploaded To IPFS

const AWS = require('aws-sdk');
const fs = require('fs');

const s3 = new AWS.S3({
    endpoint: 'https://s3.filebase.com',
    region: 'us-east-1',
    signatureVersion: 'v4',
});

fs.readFile('image.png', (err, data) => {
    if (err) {
        console.error(err);
        return;
    }
    
    const params = {
        Bucket: 'my-ipfs-bucket',
        Key: 'test/image.png',
        ContentType: 'image/png',
        Body: data,
        Metadata: { import: "car" }
    };
    
    const request = s3.putObject(params);
    request.on('httpHeaders', (statusCode, headers) => {
        console.log(`CID: ${headers['x-amz-meta-cid']}`);
    });
    request.send();
});

Uploading a Folder to IPFS

Download the ipfs-car package with the following command:

git clone https://github.com/web3-storage/ipfs-car

Install the ipfs-car package:

npx ipfs-car

Next, use ipfs-car to package a folder of files into a .car file.

This has been tested with .car archives containing 10,000 or more files. Use either of the following commands, depending on your desired workflow:

Write a .car file to the current working directory

ipfs-car --pack path/to/file/or/dir

Write a .car file to a specific directory with a specified name

ipfs-car --pack path/to/files --output path/to/write/ipfs-car.car

Create a new file with the following AWS SDK for JavaScript code:

The following code example uploads an IPFS folder to the bucket name provided and returns the folder’s CID value. Replace the following values in the code to match your configuration:

• accessKeyId: Filebase Access Key

• secretAccessKey: Filebase Secret Key

• Bucket: Your Filebase Bucket Name

• Key: The Local Path To The Object To Be Uploaded To IPFS

const AWS = require('aws-sdk');
const fs = require('fs');

const s3 = new AWS.S3({
    endpoint: 'https://s3.filebase.com',
    region: 'us-east-1',
    signatureVersion: 'v4',
});

fs.readFile('image.png', (err, data) => {
    if (err) {
        console.error(err);
        return;
    }
    
    const params = {
        Bucket: 'my-ipfs-bucket',
        Key: 'test/image.png',
        ContentType: 'image/png',
        Body: data,
        Metadata: { import: "car" }
    };
    
    const request = s3.putObject(params);
    request.on('httpHeaders', (statusCode, headers) => {
        console.log(`CID: ${headers['x-amz-meta-cid']}`);
    });
    request.send();
});

IPFS CLI

IPFS CLI is a command line tool that can be used to interact with IPFS. It can be configured to utilize different IPFS pinning services such as Filebase through the ipfs pin remote commands.

Read below to learn how to use IPFS CLI with Filebase.

Prerequisites:

• Download and install IPFS CLI.
• Sign up for a free Filebase account.
• Have your Filebase Access and Secret Keys. Learn how to view your access keys here.
• Create a Filebase IPFS Bucket. Learn how to create a bucket here.

Configure Filebase As a Pinning Service

To add Filebase as a pinning service, use the following command:

ipfs pin remote service add filebase https://api.filebase.io/v1/ipfs access-token

Replace access-token with your Filebase IPFS Pinning Service token. The access-token can be generated by navigating to the Filebase Access Keys page, then viewing the IPFS PInning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.

Then copy the generated Secret Access Token:

To Pin a CID Into Your Filebase Bucket:

ipfs pin remote add --service=filebase --name=test.png QmSp5z5RAgDhS38w7TmLMfyDXvY9i2hF6sJ4qm62SK5939

To List All Pinned Files In Your Filebase Bucket:

ipfs pin remote ls --service=filebase

To List All Pins That Are Queued, Pinning, Or Failed:

ipfs pin remote ls --service=filebase --status=queued,pinning,failed

AWS CLI

AWS CLI, or Amazon Web Services Command Line Interface, is a command line tool developed by Amazon using Python that is used for transferring data to object storage services. This is one of the most commonly used CLI tools by IT system administrators, developers, and programmers. Even though this tool is developed by Amazon, you can use it with any S3-compatible API object storage service, including Filebase, to manage your storage objects and buckets.

Prerequisites:

• Download and install the AWS CLI tool.
• Sign up for a free Filebase account.
• Have your Filebase Access and Secret Keys. Learn how to view your access keys here.

• Note the Filebase API endpoint -https://s3.filebase.com

Configuration

First, configure AWS CLI to work with Filebase and your Filebase account. To do this, open a new terminal window. From there, run the command:

aws configure

This command will generate a series of prompts, which should be filled out as such:

• Access Key ID: Filebase Access Key

• Secret Access Key: Filebase Secret Key

• Region: us-east-1

• Output Format: Optional

After completing the prompt, begin interacting with the Filebase S3 API using the AWS CLI tool. You will not need to configure AWS CLI again as long as your Access ID and Secret Access Key does not change.

All AWS CLI commands will begin with aws --endpoint https://s3.filebase.com

Creating a New Bucket

To create a new bucket on Filebase using the AWS CLI, use the command:

aws --endpoint https://s3.filebase.com s3 mb s3://[bucket-name]

Bucket names must be unique across all Filebase users, be between 3 and 63 characters long, and can contain only lowercase characters, numbers, and dashes.

Listing Buckets

The following command will list all buckets in your Filebase account:

aws --endpoint https://s3.filebase.com s3 ls

Listing the Content of a Bucket

To list the contents of a bucket, use the command:

aws --endpoint https://s3.filebase.com s3 ls s3://[bucket-name]

Uploading a File to IPFS

The CID will be returned in the response of a PutObject call. For example, if we run the following AWS CLI command:

aws --endpoint https://s3.filebase.com s3 cp test-images/7FIMFhlMf6A.jpg s3://ipfs-test --debug

The response is shown below. For convenience, we've highlighted the respective response header:

You can also call the HeadObject API to fetch the CID at any time as well:

aws --endpoint https://s3.filebase.com s3api head-object --bucket ipfs-test --key 7FIMFhlMf6A.jpg

Uploading a Folder to IPFS

A CAR file is a type of compressed archive file that contains multiple files, similar to a ZIP file. CAR files are used by the FileCoin and IPFS networks, which utilize the metadata fields to include the IPFS CIDs of each file within the archive. Filebase supports uploading CAR files to IPFS using the S3-compatible API through the PutObject or MultipartUpload methods.

For instructions on how to create a CAR file, check out our guide here:

IPFS-CAR

When you upload a CAR file, you can pass an S3 metadata header of x-amz-meta-import: car along with the request. Filebase will then import the file as a CAR, and return the resulting CID.

Below is an example using the AWS CLI, which adds the x-amz-meta prefix automatically:

aws --endpoint https://s3.filebase.com s3 cp pictures.car s3://ipfs-test --debug --metadata 'import=car'

With the specified –debug flag, the response headers are shown, which reveal the CID:

2022-06-14 19:51:41,400 - ThreadPoolExecutor-0_2 - botocore.parsers - DEBUG - Response headers:

{
'Date': 'Tue, 14 Jun 2022 23:51:41 GMT',
'Content-Type': 'application/xml'
'Transfer-Encoding': 'chunked',
'Connection': 'keep-alive',
'x-amz-meta-cid': 'bafybeieurpeyzighqrvwjqyj3szuvbqvrbijm7cdair5a422ipf2d5qnlq',
'ETag': 'W/"d8cad258a3d9bbe03a26a13a3ec43b21"',
'x-amz-request-id': '144e0415-8162-45cd-b071-e51dada956ae',
'x-amz-id-2': 'ZmlsZWJhc2UtNmQ3ZjQ5OGZmZC14ejk1Mg==',
'Server': 'Filebase'

}

IPFS Pinning Service API

To learn more about using our IPFS Pinning Service API, check out our API documentation page here:

IPFS Pinning Service API