Vendia Folder API

Working with Folders in Vendia Unis allows for the organizing of Files within a Uni. Folders can be shared or not among the various participants in a Uni by setting the appropriate Read or Write permissions. The participant (node) adding a Folder can determine which other nodes are allowed to read and/or write from the Folder.

Setup

When you add or update a file/folder, Vendia copies the object from its original location (which must be in an S3 bucket you have access to) and then stores a copy of it in each participant in your Uni.

To do this you must follow the granting permissions to the source bucket setup steps first.

Properties

Every Vendia Folder has the following properties:

• _id: The unique identifier that identifies the specific folder. This _id is consistent across all Nodes in the Uni.
• name: The name of the Folder. The name is restricted to alphanumeric characters, periods, underscores, hyphens and spaces. Names cannot start or end with spaces.
• parent: The name of the parent Folder. The name is restricted to alphanumeric characters, periods, underscores, hyphens and spaces. Names cannot start or end with spaces.
• read: List of comma separated strings that identifies the Nodes that can read the file.
• write: List of comma separated strings that identifies the Nodes that can write to the file.
• createdAt: The time the folder was added to the Node.
• updatedAt: The time the folder was last updated.

Methods

All Folder methods use the same GraphQL syntax as the rest of the Uni's API. The Folder API has operations to add, remove, list and get folders.

Add Folder

The basic GraphQL mutation to add a File to a Uni:

mutation createFolder {
  addVendia_Folder(
    input: {
      name: "FolderName",
      read: [List of Nodes],
      write: [List of Nodes]
    },
    syncMode: ASYNC
  ) {
    transaction {
      transactionId
    }
  }
}

Only the Name property is required. If you don't specify, the others properties will defaults as follows:

• Read: All Nodes in the Uni are able to read from this Folder.
• Write: Only the Node that added the Folder can write to it.

Remove Folder

The basic GraphQL mutation to remove a Folder from a Uni:

mutation removeFolder {
  removeVendia_Folder(
    input: {
      id: "your-folder-id"
    },
    syncMode: ASYNC
  ) { transaction { _id } }
}

A node must have Write permissions to the Folder itself or it's parent folder to be able to remove the folder. Further, the folder must be empty.

List Folders

The basic GraphQL mutation to list Folders in a Uni:

query listFolders {
  listVendia_FolderItems {
    Vendia_FolderItems {
      _id
      name
      parent
      read
      write
      copyStrategy
      createdTime
      updatedTime
    }
  }
}

When retrieving a list of Folders you can specify which Folder properties to return. Further, you can filter the list using standing GraphQL filter syntax on the existing properties. You will only receive those Folders for which you have Read access.

Get Folder

The basic GraphQL mutation to get a Folder from a Uni:

query getFolder {
  getVendia_Folder(id: "your-folder-id") {
    _id
    name
    createdTime
    updatedTime
    read
    write
    copyStrategy
  }
}

You must have Read permissions to get a Folder. Like listing Folders, you can specify which properties you want returned.

Folders and Files

Once you add a Folder you can add Files to the folder by prefixing the File destinationKey with the folder name. For example, if you create the folder my-folder-name, you can add a file to the my-folder-name folder with the following GraphQL.

mutation addFileToFolder {
  addVendia_File(
    input: {
      sourceBucket: "<bucket>",
      sourceKey: "<key>",
      sourceRegion: "<region>",
      destinationKey: "my-folder-name/<destination key>"
    },
    syncMode: ASYNC
  ) { transaction { _id } }
}

Your Node must have Write permissions to the Folder to be able to add the File to the Folder.

Error Message

The Folder APIs will return the standard GraphQL exceptions if invalid syntax is used. However, errors can be returned in specific instances:

• Folder already exists: Attempting to add a new Folder with the same name.
• Parent Folder does not exist: Attempting to add a sub-folder to a folder that does not exist.
• No permission to create child folder: No permissions to create a sub-folder.
• No write permissions: Attempting to add a Folder without Write permissions.

Next Steps

Developing and Using Unis

Defining Your Data Model

Integrating a Vendia chain with other Cloud, Web, and Mobile Services

Learning More

Terms and Definitions