Фолдери

Фолдери организују ваше отпремљене фајлове на контролној табли. Подразумевано су само-метаподаци — фајлови задржавају своје сопствене CID-ове и не премештају се на IPFS-у — али можете и направити снимак фолдера да га материјализујете као прави UnixFS директоријум и добијете један CID за целу целину.

Када направити снимак фолдера

Снимак фолдера је један CID IPFS директоријума који садржи сваки фајл у фолдеру, адресив по имену. Са њим можете да:

• Поделите цео фолдер преко једног URL-а: https://ipfs.ninja/ipfs/{dirCid}/
• Разрешите https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (или било који други gateway) директно
• Убаците CID у ENS contenthash за хостовање статичног сајта
• Користите га као основни CID NFT колекције тако да сваки токен упућује на ipfs://{dirCid}/<id>.json
• Закачите директоријум било где другде — сваки IPFS gateway на свету зна како да разреши UnixFS CID директоријума

Снимци су адресирани садржајем: идентичан садржај фолдера увек производи исти CID. Поновно прављење снимка фолдера који нисте мењали враћа исти CID који је враћен раније. Додавање/уклањање/преименовање фајла производи нови CID; претходни CID остаје закачен и разрешив све док не обришете његове фајлове.

Креирање фолдера

POST /folders

Параметар	Тип	Обавезно	Опис
name	string	Да	Приказано име.
parentFolderId	string | null	Не	ID родитељског фолдера за угнежђене фолдере. Изоставите за фолдер на root нивоу.

Пример

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

Враћа:

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

Новокреирани фолдери немају снимак. Поље latestSnapshot се појављује на фолдеру када позовете POST /folders/{id}/snapshot (погледајте испод) и у наредним одговорима GET /folders.

Листа фолдера

GET /folders

Враћа сваки фолдер на вашем налогу, на root нивоу и угнежђене, са CID-ом последњег снимка за сваки (ако постоји).

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

fileCount одражава тренутни садржај фолдера; latestSnapshot.fileCount одражава садржај у тренутку последњег снимка. Ако се разликују, CID снимка се и даље разрешава, али је застарео — направите нови снимак да га освежите.

Премештање фајла у фолдер

PUT /files/{cid}/move

Параметар	Тип	Обавезно	Опис
folderId	string | null	Да	ID циљног фолдера, или null за премештање фајла у root.

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

Прављење снимка фолдера (добијање CID-а UnixFS директоријума)

POST /folders/{folderId}/snapshot

Материјализује фолдер као прави UnixFS директоријум на IPFS кластеру и качи резултат. Враћа један CID за цео фолдер. Имена дечијих елемената долазе из fileName сваког фајла; дупликати се аутоматски разрешавају.

Тело захтева није потребно; параметар путање идентификује фолдер.

Пример

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

Враћа:

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

CID се такође трајно чува на реду фолдера, тако да наредни позиви GET /folders враћају га као latestSnapshot.cid без потребе за новим снимком.

Разрешавање снимка

Када је снимак закачен, CID директоријума се разрешава преко било ког IPFS gateway-а. Најједноставнији образац URL-а:

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

Кластер качи рекурзивно, тако да су и дечији елементи разрешиви — чак и ако касније обришете оригинални фајл са свог налога, копија из снимка опстаје јер је то посебно качење које рекурзивно пролази кроз директоријум.

Поновно прављење снимка

Поновно прављење снимка непромењеног фолдера враћа исти CID — CID-ови директоријума су адресирани садржајем, тако да идентичан садржај увек производи исти хеш, а позив качења на кластеру препознаје дупликат и на својој страни не ради ништа.

Напомена: сама путања за снимак ипак није бесплатна чак и када је резултат исти CID. Сваки позив чита бајтове сваког фајла назад са IPFS-а и поново их отпрема као multipart на /add крајњу тачку кластера — ту се дешава умотавање директоријумом. За типичне фолдере (≤100 малих фајлова) ово се и даље завршава за неколико секунди; за врло велике фолдере препоручује се позивање снимка само када се садржај заиста промени.

Позивање снимка након што сте додали или уклонили фајлове производи другачији CID; претходни наставља да се разрешава све док не обришете његове основне фајлове.

Ограничења

• Фолдер мора садржати бар један фајл. Празни фолдери враћају 400 — folder is empty.
• Карактери имена фајла се URL-кодирају у multipart отпремању које Kubo прихвата; URL-ови gateway-а можда захтевају percent-кодирање за размаке или не-ASCII карактере у именима фајлова.
• Снимци се рачунају у укупан број качења вашег плана тачно једном по јединственом CID-у — блокови фајлова су дедуплицирани, тако да снимак углавном додаје само мали чвор директоријума изнад фајлова које већ качите.

Ажурирање фолдера

PUT /folders/{folderId}

Параметар	Тип	Обавезно	Опис
name	string	Не	Ново приказано име.
parentFolderId	string | null	Не	Промена родитеља фолдера. null премешта га у root.

Брисање фолдера

DELETE /folders/{folderId}

Брише фолдер и рекурзивно каскадира кроз сваки фајл и подфолдер који садржи. Подлеже истој заштити дељеног CID-а као и брисање појединачних фајлова — ако други корисници и даље каче CID који сте отпремили, ваше откачивање им га не уклања.

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

Конфигурисање S3 CORS за фолдер / bucket

Фолдери изложени преко S3-компатибилног API-ја делују као bucket-и. Ако тим API-јем управљате из browser JavaScript-а, потребна су вам CORS правила на bucket-у да би browser preflight захтеви пролазили. Две еквивалентне површине трајно чувају у исту меморију:

• PUT /folders/{folderId}/cors — ова REST крајња тачка, аутентификована путем JWT-а (користи је контролна табла)
• S3 subresource PUT /{bucket}?cors — аутентификован путем SigV4 (користе га AWS SDK-ови, погледајте s3-compatibility.md)

PUT на ову крајњу тачку такође преузима име фолдера као глобално-јединствено име bucket-а ако још није преузето.

PUT /folders/{folderId}/cors

Постављање CORS правила за S3 bucket фолдера. До 5 правила по bucket-у, укупно 64 KB.

Параметар	Тип	Обавезно	Опис
rules	CorsRule[]	Да	Низ CORS правила у AWS облику (погледајте испод). Не сме бити празан.
bucketName	string	Не	Експлицитно име S3 bucket-а. Подразумевано је приказано име фолдера. Ако је жељено име већ глобално заузето, овде проследите алтернативу.

Свако CorsRule:

Поље	Тип	Обавезно	Опис
AllowedOrigins	string[]	Да	Порекла којима је дозвољено слање захтева. Подржава wildcard-ове (https://*.myapp.com). Користите * за било које порекло.
AllowedMethods	string[]	Да	Један или више од GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Не	Заглавља која прегледачи могу укључити у захтеве. Подразумевано: ниједно. Користите ["*"] за дозволу свих (препоручено за AWS SDK v3 који шаље Authorization, x-amz-* итд.).
ExposeHeaders	string[]	Не	Заглавља одговора учињена читљивим за browser JavaScript. Укључите ETag и x-amz-meta-cid ако вашој апликацији треба враћени CID.
MaxAgeSeconds	number	Не	Колико дуго прегледачи кеширају preflight. 0-86400. Подразумевано 3600.
ID	string	Не	Слободна текстуална ознака за правило.

Пример захтева

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

Враћа тренутна CORS правила плус име bucket-а (ако је преузето).

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

DELETE /folders/{folderId}/cors

Уклања сва CORS правила. Browser preflight захтеви ка bucket-у ће бити одбијени док се не поставе нова правила.

Алтернатива преко контролне табле

На страници Фајлови, мени радњи сваког фолдера има ставку S3 CORS која отвара уређивач заснован на форми. Иста основна меморија као ова REST крајња тачка и као PutBucketCors преко S3 API-ја.