# 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**:

```graphql
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**:

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

A **workspace** must have Write permissions to the Folder itself or its 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**:

```graphql
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 standard 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**:

```graphql
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.

```graphql
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.