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.

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 File has the following properties:

• _id: The unique identifier that identifies the specific file. This value 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: Only the Node that adds the File with a NEVER/ON_ACCESS copyStrategy can have write permissions to the File.
  • Note: The NEVER and ON_ACCESS options for copyStrategy are only available for non Free Tier Unis.
• 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 getVendia_File or listVendia_FileItems. Each call will generate a new URL valid for an hour.
  • Note: 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:

mutation addFile {
  addVendia_File(
    input: {
      sourceBucket: <bucket>,
      sourceKey: <key>,
      sourceRegion: <region>,
      destinationKey: <key>,
      copyStrategy: <strategy>,
      read: [List of Nodes],
      write: [List of Nodes]
    },
    syncMode: ASYNC        
  ) { transaction { _id } }
}

Only the sourceBucket, sourceKey, sourceRegion, and destinationKey properties are required. If you don't specify the others they will default to:

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

mutation updateFile {
  updateVendia_File(
    id: "my-file-id",
    input: {
      sourceBucket: "<bucket>"
      sourceKey: "<key>"
      sourceRegion: "<region>"
      destinationKey: "<key>"
    },
    syncMode: ASYNC
  ) { transaction { _id } }
}

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:

mutation removeFile {
  removeVendia_File(
    id: "my-file-id",
    syncMode: ASYNC
  ) { transaction { _id } }
}

Any node can always remove a File.

List Files

The basic GraphQL mutation to list Files in a Uni:

query listFiles {
  listVendia_FileItems(filter: {}) {
    Vendia_FileItems {
      _id
      sourceBucket
      sourceKey
      sourceRegion
      sourceVersion
      destinationKey
      copyStrategy
      read
      write
      etag
      createdTime
      updatedTime
      temporaryUrl
      fileVersion
    }
  }
}

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:

query getFile {
  getVendia_File(id: "my-file-id") {
    sourceBucket
    sourceKey
    sourceRegion
    sourceVersion
    destinationKey
    copyStrategy
    read
    write
    etag
    createdTime
    updatedTime
    temporaryUrl
    fileVersion
  }
}

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