Compatibilitate S3

Foloseste AWS SDK pentru a incarca, descarca si gestiona fisiere pe IPFS Ninja cu acelasi cod pe care il folosesti pentru Amazon S3.

Endpoint

https://s3.ipfs.ninja

Credentiale

API-ul S3 foloseste cheia ta de API IPFS Ninja pentru autentificare. Cheia ta de API serveste atat ca access key, cat si ca secret key.

Cum sa obtii credentialele

1. Acceseaza Dashboard > API Keys
2. Apasa Create API key si da-i un nume (ex: "S3 access")
3. Copiaza cheia completa imediat — este afisata o singura data si nu poate fi recuperata ulterior

Cheia ta arata astfel:

bws_628bba35e9e0079d9ff9c392b1b55a7b
├──────────┘└──────────────────────────┘
 prefix (12 chars)    rest of key

Maparea la credentiale AWS

Parametru AWS	Valoare	Exemplu
accessKeyId	Primele 12 caractere ale cheii tale de API	bws_628bba35
secretAccessKey	Cheia de API completa (toate cele 36 de caractere)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Intotdeauna us-east-1	us-east-1

WARNING

Cheia de API completa este afisata o singura data cand o creezi. Daca o pierzi, sterge cheia si creeaza una noua din pagina API Keys.

Start Rapid

import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

// Upload a file
const put = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "hello.json",
  Body: JSON.stringify({ hello: "IPFS" }),
  ContentType: "application/json"
}));

console.log("CID:", put.Metadata?.cid);
// CID: QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy

Buckets = Foldere

Bucket-urile S3 corespund folderelor tale din IPFS Ninja. Cand incarci un fisier intr-un bucket, acesta este stocat in folderul corespunzator. Cand listezi obiectele dintr-un bucket, vezi fisierele din acel folder.

Operatie S3	Echivalent IPFS Ninja
CreateBucket	Creeaza un folder nou
ListBuckets	Listeaza folderele tale
DeleteBucket	Sterge un folder si toate fisierele din el
PutObject in bucket	Incarca fisier in folder
ListObjectsV2 pe bucket	Listeaza fisierele din folder

import { ListBucketsCommand, CreateBucketCommand, PutObjectCommand } from "@aws-sdk/client-s3";

// Create a bucket (= create a folder)
await s3.send(new CreateBucketCommand({ Bucket: "nft-metadata" }));

// Upload a file into the folder
await s3.send(new PutObjectCommand({
  Bucket: "nft-metadata",      // ← folder name
  Key: "token-42.json",        // ← filename within the folder
  Body: JSON.stringify({ name: "My NFT #42" })
}));

// List buckets (= list your folders)
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets);
// [{ Name: "nft-metadata", CreationDate: "2026-04-13T..." }]

TIP

Folderele create prin API-ul S3 sunt aceleasi foldere vizibile in Dashboard-ul tau. Poti organiza fisiere atat din API-ul S3, cat si din API-ul REST, sau din interfata web — toate impart acelasi sistem de foldere.

INFO

Spre deosebire de Amazon S3, folderele IPFS Ninja sunt plate implicit. Pentru a crea structuri ierarhice, foloseste endpoint-urile de foldere din API-ul REST cu parentFolderId. Din API-ul S3, foloseste prefixe in chei (ex: images/photo.png) pentru a organiza in cadrul unui folder.

Operatii Suportate

PutObject

Incarca un fisier pe IPFS. Fisierul este fixat (pinned), scanat pentru securitate, iar CID-ul este returnat in headerele ETag si x-amz-meta-cid.

import { PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "photo.png",
  Body: fs.readFileSync("photo.png"),
  ContentType: "image/png"
}));

console.log("CID:", result.ETag);

# curl equivalent
curl -X PUT "https://s3.ipfs.ninja/my-project/photo.png" \
  --data-binary @photo.png \
  -H "Content-Type: image/png" \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "bws_628bba35:bws_628bba35e9e0079d9ff9c392b1b55a7b"

GetObject

Descarca un fisier dupa cheia sa (numele fisierului) sau CID.

import { GetObjectCommand } from "@aws-sdk/client-s3";

const result = await s3.send(new GetObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

const body = await result.Body.transformToByteArray();
console.log("Size:", body.length);
console.log("CID:", result.Metadata?.cid);

HeadObject

Obtine metadatele fisierului fara a descarca continutul.

import { HeadObjectCommand } from "@aws-sdk/client-s3";

const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

console.log("Size:", head.ContentLength);
console.log("Type:", head.ContentType);
console.log("CID:", head.Metadata?.cid);

DeleteObject

Elimina fixarea (unpin) unui fisier de pe IPFS si il sterge din contul tau.

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

ListObjectsV2

Listeaza fisierele dintr-un bucket cu filtrare optionala dupa prefix si paginare.

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const list = await s3.send(new ListObjectsV2Command({
  Bucket: "my-project",
  Prefix: "images/",
  MaxKeys: 100
}));

for (const obj of list.Contents ?? []) {
  console.log(obj.Key, obj.Size, obj.ETag); // ETag = CID
}

Multipart Upload

Incarca fisiere mari (pana la 5 GB) folosind multipart upload. AWS SDK se ocupa de asta automat:

import { Upload } from "@aws-sdk/lib-storage";
import fs from "fs";

const upload = new Upload({
  client: s3,
  params: {
    Bucket: "my-project",
    Key: "large-dataset.tar.gz",
    Body: fs.createReadStream("large-dataset.tar.gz"),
    ContentType: "application/gzip"
  },
  partSize: 10 * 1024 * 1024, // 10 MB per part
});

upload.on("httpUploadProgress", (progress) => {
  console.log(`Uploaded ${progress.loaded} of ${progress.total} bytes`);
});

const result = await upload.done();
console.log("CID:", result.ETag);

Sau controleaza partile manual:

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand
} from "@aws-sdk/client-s3";

// 1. Start
const { UploadId } = await s3.send(new CreateMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin"
}));

// 2. Upload parts
const part1 = await s3.send(new UploadPartCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  PartNumber: 1,
  Body: chunk1
}));

// 3. Complete
const result = await s3.send(new CompleteMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  MultipartUpload: {
    Parts: [{ PartNumber: 1, ETag: part1.ETag }]
  }
}));

Exemplu Python

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.ipfs.ninja",
    aws_access_key_id="bws_628bba35",
    aws_secret_access_key="bws_628bba35e9e0079d9ff9c392b1b55a7b",
    region_name="us-east-1"
)

# Upload
s3.put_object(
    Bucket="my-project",
    Key="data.json",
    Body=b'{"hello": "IPFS"}',
    ContentType="application/json"
)

# List files
response = s3.list_objects_v2(Bucket="my-project")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

# Download
result = s3.get_object(Bucket="my-project", Key="data.json")
print(result["Body"].read())

Exemplu Go

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    client := s3.New(s3.Options{
        BaseEndpoint: aws.String("https://s3.ipfs.ninja"),
        Region:       "us-east-1",
        Credentials:  credentials.NewStaticCredentialsProvider("bws_628bba35", "bws_628bba35e9e0...", ""),
        UsePathStyle: true,
    })

    _, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:      aws.String("my-project"),
        Key:         aws.String("hello.txt"),
        Body:        strings.NewReader("Hello, IPFS!"),
        ContentType: aws.String("text/plain"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Uploaded!")
}

Diferente fata de Amazon S3

Functionalitate	Amazon S3	IPFS Ninja S3
Model de stocare	Obiecte mutabile	Adresare dupa continut (CID-uri imutabile)
Comportament la suprascriere	Inlocuieste obiectul pe loc	Creeaza CID nou, CID-ul vechi ramane accesibil
Versionare	Suportata	Nesuportata (foloseste CID-uri pentru versionare)
Criptare pe server	Suportata	Nesuportata (continutul este pe IPFS)
Politici de ciclu de viata	Suportate	Nesuportate
Politici de bucket / ACL-uri	Suportate	Foloseste modurile de acces gateway
URL-uri pre-semnate	Suportate	Foloseste token-uri de incarcare semnate
Dimensiune maxima obiect	5 TB	5 GB (multipart), 100 MB (PUT singular)
Regiuni	Multi-regiune	Doar us-east-1
Valoare ETag	Hash MD5	IPFS CID
Headere suplimentare	S3 standard	x-amz-meta-cid (IPFS CID)

Migrare de la Amazon S3

Inlocuieste configuratia clientului S3:

 const s3 = new S3Client({
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "AKIA...",
-    secretAccessKey: "wJalrX..."
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
+  forcePathStyle: true
 });

Apelurile tale existente PutObject, GetObject, ListObjectsV2 si DeleteObject functioneaza fara modificari.

Migrare de la Filebase

Inlocuieste URL-ul endpoint-ului:

 const s3 = new S3Client({
-  endpoint: "https://s3.filebase.com",
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "FILEBASE_KEY",
-    secretAccessKey: "FILEBASE_SECRET"
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
   forcePathStyle: true
 });