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.

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.
  • Owner: The node that owns this Folder.
  • 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:

add_Folder_async(
    input: {
        Name: <Folder Name>,
        Read: [List of Nodes],
        Write: [List of Nodes]
    }
) { error }

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:

remove_Folder_async(
    input: {
        id: <folder-id>
    }
) { error }

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:

list_Folders( <Optional Filter> ) {
    _Folders { <Folder Properties> }
}

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:

get_Folder(id: <folder-id>) {
    { <Folder Properties> }
}

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 docs, you can add a file to the docs folder with the following GraphQL.

add_Folder_async(
    input: {
        SourceBucket: "<bucket>",
        SourceKey: "<key>",
        SourceRegion: "<region>",
        DestinationKey: "docs/<destination key>"
    }
) { error }

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

Show table of contents
Edit this page