The Folder is a high-level abstraction that allows users to easily operate on their DAG, such as adding, updating, or removing links. While not a new concept, it simplifies multiple IPFS node operations into a single API. To enable smooth operations on TB-level single DAGs using a folder, users must first import their DAG into the folder using PUT /api/v0/folder/{CID}. This allows GW3 to shard the DAGs across multiple services. After that, POST /folder/operation can be used to update your DAGs.

Folder Import

curl -X PUT "https://gw3.io/api/v0/folder/{cid}?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Import a previously pinned CID to the folder system. For large DAGs (with many links), consider setting an extended timeout period (1 second per link).

• cid
  • Required: Yes
  • Description: A CID that has already been pinned by GW3.
  • Example: bafybeidbcbdlaqgn6yvp6wc4ca66jl2zazwbzh46qtvovpzznxgomjxtce
• ts
  • Required: Yes
  • Description: A query parameter representing the current UNIX timestamp.
  • Example: 1688644825

Response body

{
    "code": 200,
    "msg": "ok"
}

Folder Operation

curl -X POST "https://gw3.io/api/v0/folder/operation?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Specify the old CID root, links you want to add/update in the DAG, and links you wish to remove. The API will combine the changes into a new DAG and return it to the user.

• ts
  • Required: Yes
  • Description: A query parameter that represents the current UNIX timestamp.
  • Example: 1688644825
• cid
  • Required: Yes
  • Description: A CID that has already been imported to the folder or generated by the folder.
  • Example: bafybeidbcbdlaqgn6yvp6wc4ca66jl2zazwbzh46qtvovpzznxgomjxtce
• add
  • Required: No
  • Description: An array of tuples specifying the link (name –> CID) you want to add to the DAG. If a link with the same name already exists in the old DAG, the old link will be replaced. All CIDs must be pinned by GW3 first.
  • Example: [["my_license", "k2cwuee0yyjcb7195g3gkv0ejhp9b37zf3glzlayg5h81xgun5jd9x1i"]]
• remove
  • Required: No
  • Description: Remove existing links in the DAG by their names.
  • Example: ["README.md"]
• pin_new
  • Required: No
  • Description: Pin the new DAG. If the new CID is already pinned, the API will return an error.
  • Example: true
• unpin_old
  • Required: No
  • Description: Unpin the old DAG; this requires pin_new to be true. If the old DAG is still being used by another of your pinned DAGs, an error will be returned.
  • Example: true

Request body

{
   "cid":"k2cwuee0yyjcb7195g3gkv0ejhp9b37zf3glzlayg5h81xgun5jd9x1i",
   "remove":[
      "README.md",
      "package.json"
   ],
   "add":[
      ["test.config","k2jmtxts79pbodzrx8nyndvwvavvd70k3fnbo0ev1lc47ho40t98ocup"]
   ],
   "pin_new":true,
   "unpin_old":true
}

Response Body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "cid": "QmPUmNQ76J748c3iboBCRnxSge39sftmn9zSyLXjA1GBvc"
    }
}

Use Case Condition

1. All CIDs used in the /api/v0/folder/operation must be pinned by GW3 first.
2. Cannot add and remove the same link name in a single operation call. ```