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.
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
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
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.
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
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
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
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.
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
.car
file to the current working directoryipfs-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
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.
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.
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:
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:
IPFS Pinning Service API
To learn more about using our IPFS Pinning Service API, check out our API documentation page here:
Last updated