Mape

Mape organiziraju vaše prenesene datoteke na nadzornoj ploči. Prema zadanim postavkama sadrže samo metapodatke — datoteke zadržavaju svoje vlastite CID-ove i ne premještaju se na IPFS-u — no možete i snimiti mapu (snapshot) kako biste je materijalizirali kao pravi UnixFS direktorij i dobili jedan CID za cijelu mapu.

Kada snimiti mapu

Snimka mape je jedan CID IPFS direktorija koji sadrži svaku datoteku u mapi, adresabilnu prema imenu. Uz nju možete:

• Podijeliti cijelu mapu putem jednog URL-a: https://ipfs.ninja/ipfs/{dirCid}/
• Razriješiti https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (ili bilo koji drugi gateway) izravno
• Ubaciti CID u ENS contenthash za hostanje statične stranice
• Koristiti ga kao osnovni CID NFT kolekcije tako da svaki token referencira ipfs://{dirCid}/<id>.json
• Prikvačiti direktorij bilo gdje drugdje — svaki IPFS gateway na svijetu zna razriješiti CID UnixFS direktorija

Snimke su adresirane prema sadržaju: identičan sadržaj mape uvijek proizvodi isti CID. Ponovno snimanje mape koju niste promijenili vraća isti CID kao i prije. Dodavanje/uklanjanje/preimenovanje datoteke proizvodi novi CID; prethodni CID ostaje prikvačen i razrješiv sve dok ne izbrišete njegove datoteke.

Stvaranje mape

POST /folders

Parametar	Tip	Obavezno	Opis
name	string	Da	Prikazano ime.
parentFolderId	string | null	Ne	ID nadređene mape za ugniježđene mape. Izostavite za mapu na korijenskoj razini.

Primjer

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" }'

Vraća:

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

Novostvorene mape nemaju snimku. Polje latestSnapshot pojavljuje se na mapi tek nakon poziva POST /folders/{id}/snapshot (vidi ispod) te u sljedećim odgovorima na GET /folders.

Popis mapa

GET /folders

Vraća sve mape na vašem računu, one na korijenskoj razini i ugniježđene, s CID-om zadnje snimke za svaku (ako postoji).

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

fileCount odražava trenutni sadržaj mape; latestSnapshot.fileCount odražava sadržaj u trenutku zadnje snimke. Ako se razlikuju, CID snimke i dalje se razrješava, ali je zastario — ponovno snimite mapu kako biste ga osvježili.

Premještanje datoteke u mapu

PUT /files/{cid}/move

Parametar	Tip	Obavezno	Opis
folderId	string | null	Da	ID ciljne mape, ili null za premještanje datoteke u korijen.

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-…" }'

Snimka mape (dohvaćanje CID-a UnixFS direktorija)

POST /folders/{folderId}/snapshot

Materijalizirajte mapu kao pravi UnixFS direktorij na IPFS klasteru i prikvačite rezultat. Vraća jedan CID za cijelu mapu. Imena podređenih elemenata dolaze iz fileName svake datoteke; duplikati se automatski razrješavaju.

Tijelo zahtjeva nije potrebno; parametar putanje identificira mapu.

Primjer

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

Vraća:

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

CID se također trajno pohranjuje uz redak mape, tako da naknadni pozivi GET /folders vraćaju ga kao latestSnapshot.cid bez potrebe za novom snimkom.

Razrješavanje snimke

Jednom kad je snimka prikvačena, CID direktorija razrješava se putem bilo kojeg IPFS gatewaya. Najjednostavniji obrazac URL-a:

https://ipfs.ninja/ipfs/{dirCid}/         → popis direktorija
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → ta jedna datoteka

Klaster prikvačuje rekurzivno, tako da su podređeni elementi također razrješivi — čak i ako kasnije izbrišete izvornu datoteku iz svog računa, kopija iz snimke preživljava jer je riječ o zasebnom prikvačenju koje rekurzivno prolazi kroz direktorij.

Ponovno snimanje

Ponovno snimanje nepromijenjene mape vraća isti CID — CID-ovi direktorija adresirani su prema sadržaju, pa identičan sadržaj uvijek proizvodi isti hash, a klaster prepoznaje duplikat prilikom prikvačivanja i na svojoj strani to ne radi ništa (no-op).

Napomena: sama putanja snimke nije besplatna čak i kad je rezultat isti CID. Svaki poziv čita bajtove svake datoteke natrag s IPFS-a i ponovno ih prenosi kao multipart na /add endpoint klastera — tu se događa omatanje u direktorij (wrap-with-directory). Za tipične mape (≤100 malih datoteka) ovo se i dalje dovršava u nekoliko sekundi; za vrlo velike mape preporučuje se pozivati snimku samo kad se sadržaj stvarno promijenio.

Pozivanje snimke nakon što ste dodali ili uklonili datoteke proizvodi drukčiji CID; prethodni se i dalje razrješava sve dok ne izbrišete njegove temeljne datoteke.

Ograničenja

• Mapa mora sadržavati barem jednu datoteku. Prazne mape vraćaju 400 — folder is empty.
• Znakovi u imenu datoteke URL-encode-aju se u multipart uploadu koji Kubo prihvaća; URL-ovi gatewaya možda će trebati percent-encoding za razmake ili ne-ASCII znakove u vašim imenima datoteka.
• Snimke se ubrajaju u ukupan broj prikvačenja vašeg plana točno jednom po jedinstvenom CID-u — blokovi datoteka deduplicirani su, tako da snimka uglavnom dodaje samo mali direktorijski čvor povrh datoteka koje već prikvačujete.

Ažuriranje mape

PUT /folders/{folderId}

Parametar	Tip	Obavezno	Opis
name	string	Ne	Novo prikazano ime.
parentFolderId	string | null	Ne	Promjena nadređene mape. null premješta mapu u korijen.

Brisanje mape

DELETE /folders/{folderId}

Briše mapu i rekurzivno kaskadno briše svaku datoteku i podmapu koju sadrži. Podliježe istoj sigurnosnoj zaštiti dijeljenog CID-a kao i pojedinačna brisanja datoteka — ako drugi korisnici i dalje prikvačuju CID koji ste prenijeli, vaše uklanjanje prikvačenja ne uklanja ga za njih.

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

Konfiguracija S3 CORS-a za mapu / bucket

Mape izložene putem S3-kompatibilnog API-ja djeluju kao bucketi. Ako tu API pokrećete iz JavaScripta u pregledniku, potrebna su vam CORS pravila na bucketu kako bi preflight zahtjevi preglednika prošli. Dvije ekvivalentne površine spremaju podatke u istu pohranu:

• PUT /folders/{folderId}/cors — ovaj REST endpoint, autenticiran JWT-om (koristi ga nadzorna ploča)
• S3 podresurs PUT /{bucket}?cors — autenticiran SigV4-om (koriste ga AWS SDK-ovi, vidi s3-compatibility.md)

PUT na ovaj endpoint također zauzima ime mape kao globalno jedinstveno ime bucketa, ako ono još nije zauzeto.

PUT /folders/{folderId}/cors

Postavite CORS pravila za S3 bucket mape. Do 5 pravila po bucketu, ukupno 64 KB.

Parametar	Tip	Obavezno	Opis
rules	CorsRule[]	Da	Polje CORS pravila u AWS obliku (vidi ispod). Ne smije biti prazno.
bucketName	string	Ne	Eksplicitno ime S3 bucketa. Zadano je prikazano ime mape. Ako je željeno ime već zauzeto globalno, ovdje navedite alternativu.

Svako CorsRule:

Field	Type	Required	Description
AllowedOrigins	string[]	Da	Podrijetla kojima je dopušteno slati zahtjeve. Podržava wildcard oznake (https://*.myapp.com). Koristite * za bilo koje podrijetlo.
AllowedMethods	string[]	Da	Jedna ili više od GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ne	Zaglavlja koja preglednici mogu uključiti u zahtjeve. Zadano: nijedno. Koristite ["*"] za dopuštanje svih (preporučeno za AWS SDK v3 koji šalje Authorization, x-amz-*, itd.).
ExposeHeaders	string[]	Ne	Zaglavlja odgovora učinjena čitljivima JavaScriptu u pregledniku. Uključite ETag i x-amz-meta-cid ako vašoj aplikaciji treba vraćeni CID.
MaxAgeSeconds	number	Ne	Koliko dugo preglednici keširaju preflight. 0-86400. Zadano 3600.
ID	string	Ne	Slobodna tekstualna oznaka za pravilo.

Primjer zahtjeva

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

Vraća trenutna CORS pravila te ime bucketa (ako je zauzeto).

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

DELETE /folders/{folderId}/cors

Uklanja sva CORS pravila. Preflight zahtjevi preglednika prema bucketu neće uspijevati (fail closed) dok se ne postave nova pravila.

Alternativa u nadzornoj ploči

Na stranici Datoteke, izbornik radnji svake mape ima stavku S3 CORS koja otvara uređivač temeljen na obrascu. Ista temeljna pohrana kao i ovaj REST endpoint te kao PutBucketCors putem S3 API-ja.