Folder API

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

Properties

Every Vendia Folder has the following properties:

• _id: The unique identifier that identifies the specific folder. This _id value is consistent across all workspaces in the project.
• 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 workspace identifiers that specifies which workspaces can read the folder.
• write: List of comma separated workspace identifiers that can write to the folder.
• createdAt: The time the folder was added to the workspace.
• updatedAt: The time the folder was last updated.

Methods

All Folder methods use the same GraphQL syntax as the rest of the project’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 project:

mutation createFolder {
  addVendia_Folder(
    input: { name: "FolderName", read: ["*"], write: ["Node1", "Node2"] }
    syncMode: ASYNC
  ) {
    transaction {
      transactionId
    }
  }
}

Only the name property is required. If you don’t specify, the other properties will default as follows:

• Read: All workspaces in the project are able to read from this Folder.
• Write: Only the workspace that added the Folder can write to it.

Remove Folder

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

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

A workspace 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 project:

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 project:

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.

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

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

Error Messages

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.