Vendia File API

Working with Files in Vendia Unis allows for the sharing of large, unstructured data objects across all participants in a Uni. Vendia’s Files are versioned and each action on a File is captured in the Uni’s ledger. This means that any actions taken on a File are recorded, providing a lineage for the File. Files are consistent across all the participants in the Uni and can be shared using Read or Write permissions. The participant (node) adding the File can determine which other nodes are allowed to read and/or write the File.

To learn more about how to upload/download Files into and out of your Uni see the Working with Files page.

Properties

Every Vendia File has the following properties:

  • id: The unique identifier that identifies the specific file. This id is consistent across all Nodes in the Uni.
  • SourceBucket: The source Cloud Storage bucket where the data was retrieved from when adding the file initially.
  • SourceKey: The source Cloud Storage object whose data was copied to create the file.
  • SourceRegion: The source region of Cloud Storage bucket and object.
  • SourceVersion: The source version of the Cloud Storage object.
  • DestinationKey: The unique name of the file in the Uni. The name is restricted to alphanumeric characters, periods, underscores, hyphens and spaces. Names cannot start with spaces. Names can include forward slashes to indicate the folder, however, the folder must exist already and names cannot end with a forward slash or spaces.
  • CopyStrategy: The copy strategy used when managing this file in the Uni. The default strategy is ALWAYS.
    • The three copy strategy options are:
      • ALWAYS: Every Node in the Uni has its own copy of the File.
      • NEVER: Only the owning Node (the Node which added the file initially) has a copy. All other nodes have a “symbolic link” to the file.
      • ON_ACCESS: Initially only the owning Node has a copy. However, when any non-owning Node accesses the File, the File will be copied to its Node.
      • Note:: The NEVER and ON_ACCESS options are only available for non Free Tier Unis. Additionally, only the Node that adds the File with a NEVER/ON_ACCESS CopyStrategy can have write permissions to the File.
  • 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.
  • Etag: A hash of the file contents. This value will be consistent across nodes in the Uni.
  • CreatedAt: The time the file was added to the Node.
  • UpdatedAt: The time the file was last updated.
  • TemporaryUrl: A URL that provides non-gated access to the File’s contents. The URL is only valid for one hour after generation. This property can be returned by a call to get_File or list_Files. Each call will generate a new URL valid for an hour.
    • Note: The TemporaryURL is only available for non Free Tier Unis.

Methods

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

Add File

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

add_File_async(
    input: {
        SourceBucket: <bucket>,
        SourceKey: <key>,
        SourceRegion: <region>,
        DestinationKey: <key>,
        CopyStrategy: <strategy>,
        Read: [List of Nodes],
        Write: [List of Nodes]
    }
) { error }

Only the SourceBucket, SourceKey, SourceRegion, and DestinationKey properties are required. If you don't specify the others the defaults are:

  • CopyStrategy: ALWAYS - Every Node in the Uni has their own copy of the File.
  • Read: All Nodes in the Uni are able to read this File.
  • Write: Only the Node that added the File has write permissions.
  • SourceVersion: This parameter is only necessary is you are attempting to copy a specific version of the source object.

Update File

The basic GraphQL mutation to update a File in a Uni:

update_File_async(
    input: {
        id: <file-id>,
        SourceBucket: <bucket>,
        SourceKey: <key>,
        SourceRegion: <region>,
        DestinationKey: <key>
    }
) { error }

You must provide the file-id of the File you are attempting to update and the DestinationKey name must remain unchanged. All other parameters can be updated similar to adding a File. You must have existing Write permission to be able to update a File.

Remove File

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

remove_File_async(
    input: {
        id: <file-id>
    }
) { error }

Any node can always remove a File.

List Files

The basic GraphQL mutation to list Files in a Uni:

list_Files( <Optional Filter> ) {
    _Files { <File Properties> }
}

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

Get File

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

get_File(id: <file-id>) {
    { <File Properties> }
}

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

Error Message

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

  • File already exists: Attempting to add a new File with the same DestinationKey name.
  • File destination key mismatch: Attempting to update a File with a different DestinationKey name.
  • No write permissions: Attempting to update a File without Write permissions.
  • Can't update permissions: Attempting to update permissions on a File you are not the owner of.
  • Can't update copy strategy: Attempting to update copy strategy on a File you are not the owner of.
  • File not found: Attempting to remove a file that doesn't exist.
  • Folder not found: Attempting to add a File to a Folder that doesn't exist.
  • No permission to write to folder: No permissions to add Files to the specified folder.

Limits

See Uni limits

Next Steps

Developing and Using Unis

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

Learning More

Terms and Definitions

Show table of contents
Edit this page