Foldere

Folderele organizează fișierele încărcate în dashboard. Sunt doar-metadate în mod implicit — fișierele își păstrează propriile CID-uri și nu sunt mutate pe IPFS — dar puteți de asemenea face un instantaneu (snapshot) al unui folder pentru a-l materializa ca un director UnixFS real și a obține un singur CID pentru tot ansamblul.

Când să faceți un instantaneu al unui folder

Un instantaneu de folder este un singur CID de director IPFS care conține fiecare fișier din folder, adresabil după nume. Cu el puteți:

• Distribui întregul folder printr-un singur URL: https://ipfs.ninja/ipfs/{dirCid}/
• Rezolva https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (sau orice alt gateway) direct
• Introduce CID-ul într-un contenthash ENS pentru a găzdui un site static
• Îl folosi ca CID de bază al unei colecții NFT, astfel încât fiecare token să facă referire la ipfs://{dirCid}/<id>.json
• Fixa directorul oriunde altundeva — fiecare gateway IPFS din lume știe să rezolve un CID de director UnixFS

Instantaneele sunt adresate după conținut: conținutul identic al unui folder produce întotdeauna același CID. Refacerea instantaneului unui folder pe care nu l-ați modificat returnează același CID ca înainte. Adăugarea/eliminarea/redenumirea unui fișier produce un CID nou; CID-ul anterior rămâne fixat și rezolvabil atât timp cât nu ștergeți fișierele sale.

Creare folder

POST /folders

Parametru	Tip	Obligatoriu	Descriere
name	string	Da	Numele afișat.
parentFolderId	string | null	Nu	ID-ul folderului părinte pentru foldere imbricate. Omiteți pentru un folder la nivel rădăcină.

Exemplu

curl -X POST https://api.ipfs.ninja/folders \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My NFT collection" }'

Returnează:

{
  "folderId": "1f8e2c3a-…",
  "name": "My NFT collection",
  "parentFolderId": null,
  "createdAt": 1746360000000
}

Folderele nou-create nu au niciun instantaneu. Câmpul latestSnapshot apare pe folder odată ce apelați POST /folders/{id}/snapshot (vezi mai jos) și pe răspunsurile ulterioare la GET /folders.

Listare foldere

GET /folders

Returnează fiecare folder din contul dvs., la nivel rădăcină și imbricat, cu CID-ul ultimului instantaneu pentru fiecare (dacă există).

[
  {
    "folderId": "1f8e2c3a-…",
    "name": "My NFT collection",
    "parentFolderId": null,
    "createdAt": 1746360000000,
    "fileCount": 42,
    "latestSnapshot": {
      "cid": "QmRZx5…",
      "takenAt": 1746421000000,
      "fileCount": 42
    }
  }
]

fileCount reflectă conținutul curent al folderului; latestSnapshot.fileCount reflectă conținutul la momentul ultimului instantaneu. Dacă diferă, CID-ul instantaneului tot se rezolvă, dar este învechit — refaceți instantaneul pentru a-l actualiza.

Mutarea unui fișier într-un folder

PUT /files/{cid}/move

Parametru	Tip	Obligatoriu	Descriere
folderId	string | null	Da	ID-ul folderului țintă, sau null pentru a muta fișierul la rădăcină.

curl -X PUT https://api.ipfs.ninja/files/Qm.../move \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "1f8e2c3a-…" }'

Instantaneu al unui folder (obținerea unui CID de director UnixFS)

POST /folders/{folderId}/snapshot

Materializează folderul ca un director UnixFS real pe clusterul IPFS și fixează rezultatul. Returnează un singur CID pentru întregul folder. Numele copiilor provin din fileName-ul fiecărui fișier; duplicatele sunt de-coliziate automat.

Nu este necesar niciun corp de cerere; parametrul de cale identifică folderul.

Exemplu

curl -X POST https://api.ipfs.ninja/folders/1f8e2c3a-.../snapshot \
  -H "X-Api-Key: bws_your_api_key_here"

Returnează:

{
  "ok": true,
  "folderId": "1f8e2c3a-…",
  "cid": "QmRZx5VgFHDsG7ECvaKkZBS4ydmkdAkDyaKyF71RYvh8",
  "fileCount": 42,
  "sizeBytes": 8421376,
  "takenAt": 1746421000000,
  "ipfsUrl": "https://ipfs.ninja/ipfs/QmRZx5.../"
}

CID-ul este de asemenea persistat pe rândul folderului, astfel încât apelurile ulterioare GET /folders îl returnează ca latestSnapshot.cid fără a fi nevoie de un alt instantaneu.

Rezolvarea unui instantaneu

Odată ce un instantaneu este fixat, CID-ul directorului se rezolvă prin orice gateway IPFS. Cel mai simplu model de URL:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

Clusterul fixează recursiv, deci și copiii sunt rezolvabili — chiar dacă ștergeți ulterior fișierul original din contul dvs., copia din instantaneu supraviețuiește deoarece este o fixare separată care recurge prin director.

Refacerea instantaneului

Refacerea instantaneului unui folder neschimbat returnează același CID — CID-urile de director sunt adresate după conținut, deci conținutul identic produce întotdeauna același hash, iar apelul de fixare al clusterului recunoaște duplicatul și este un no-op din partea sa.

Notă: calea de instantaneu în sine nu este gratuită chiar și atunci când rezultatul este același CID. Fiecare apel citește din nou octeții fiecărui fișier de pe IPFS și îi reîncarcă ca multipart către endpoint-ul /add al clusterului — acolo are loc împachetarea cu directorul. Pentru foldere tipice (≤100 de fișiere mici) acest lucru se finalizează totuși în câteva secunde; pentru foldere foarte mari preferați să apelați instantaneul doar atunci când conținutul s-a schimbat efectiv.

Apelarea instantaneului după ce ați adăugat sau eliminat fișiere produce un CID diferit; cel anterior continuă să se rezolve atât timp cât nu ștergeți fișierele sale de bază.

Limite

• Folderul trebuie să conțină cel puțin un fișier. Folderele goale returnează 400 — folder is empty.
• Caracterele din numele fișierului sunt codificate URL în încărcarea multipart acceptată de Kubo; URL-urile de gateway pot necesita codificare procentuală pentru spații sau caractere non-ASCII din numele fișierelor dvs.
• Instantaneele contează în totalul de fixări al planului dvs. exact o dată per CID unic — blocurile de fișiere sunt deduplicate, astfel încât instantaneul adaugă în principal un mic nod de director peste fișierele pe care le fixați deja.

Actualizarea unui folder

PUT /folders/{folderId}

Parametru	Tip	Obligatoriu	Descriere
name	string	Nu	Numele afișat nou.
parentFolderId	string | null	Nu	Re-atribuie un părinte folderului. null îl mută la rădăcină.

Ștergerea unui folder

DELETE /folders/{folderId}

Șterge folderul și propagă recursiv prin fiecare fișier și subfolder pe care îl conține. Supus aceleiași protecții de siguranță pentru CID-uri partajate ca și ștergerile individuale de fișiere — dacă alți utilizatori încă fixează un CID pe care l-ați încărcat, anularea fixării dvs. nu îl elimină pentru ei.

{
  "deleted": true,
  "filesDeleted": 42,
  "foldersDeleted": 3
}

Configurarea CORS S3 pentru un folder / bucket

Folderele expuse prin API-ul compatibil S3 se comportă ca bucket-uri. Dacă folosiți acel API din JavaScript de browser, aveți nevoie de reguli CORS pe bucket pentru ca preflight-urile browserului să treacă. Două suprafețe echivalente persistă în același depozit:

• PUT /folders/{folderId}/cors — acest endpoint REST, autentificat prin JWT (folosit de dashboard)
• Subresursa S3 PUT /{bucket}?cors — autentificată prin SigV4 (folosită de SDK-urile AWS, vezi s3-compatibility.md)

PUT-ul de pe acest endpoint de asemenea revendică numele folderului ca bucket unic global dacă nu a fost deja revendicat.

PUT /folders/{folderId}/cors

Setează regulile CORS pentru bucket-ul S3 al folderului. Până la 5 reguli per bucket, 64 KB în total.

Parametru	Tip	Obligatoriu	Descriere
rules	CorsRule[]	Da	Array de reguli CORS în formatul AWS (vezi mai jos). Nu poate fi gol.
bucketName	string	Nu	Nume explicit de bucket S3. Implicit este numele afișat al folderului. Dacă numele dorit este deja revendicat la nivel global, transmiteți aici o alternativă.

Fiecare CorsRule:

Câmp	Tip	Obligatoriu	Descriere
AllowedOrigins	string[]	Da	Originile cărora li se permite să trimită cereri. Suportă wildcard-uri (https://*.myapp.com). Folosiți * pentru orice origine.
AllowedMethods	string[]	Da	Una sau mai multe dintre GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nu	Antetele pe care browserele le pot include în cereri. Implicit: niciunul. Folosiți ["*"] pentru a le permite pe toate (recomandat pentru AWS SDK v3 care trimite Authorization, x-amz-*, etc.).
ExposeHeaders	string[]	Nu	Antetele de răspuns care devin lizibile din JavaScript-ul browserului. Includeți ETag și x-amz-meta-cid dacă aplicația dvs. are nevoie de CID-ul returnat.
MaxAgeSeconds	number	Nu	Cât timp păstrează browserele preflight-ul în cache. 0-86400. Implicit 3600.
ID	string	Nu	Etichetă liberă pentru regulă.

Exemplu de cerere

curl -X PUT https://api.ipfs.ninja/folders/17f6dfd8-519c-4d0e-8f3a-5988a1d34ef2/cors \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }]
  }'

Response 200 OK

{ "success": true, "rules": [ { "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"], "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"], "AllowedHeaders": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"], "MaxAgeSeconds": 3600 } ] }

GET /folders/{folderId}/cors

Returnează regulile CORS curente plus numele bucket-ului (dacă a fost revendicat).

{
  "rules": [ … ],
  "bucketName": "my-project"
}

DELETE /folders/{folderId}/cors

Elimină toate regulile CORS. Preflight-urile browserului către bucket vor eșua în mod implicit (fail-closed) până la setarea unor reguli noi.

Alternativă din dashboard

Pe pagina Fișiere, meniul de acțiuni al fiecărui folder are o intrare S3 CORS care deschide un editor bazat pe formular. Același depozit de bază ca acest endpoint REST și ca PutBucketCors prin API-ul S3.