Files API

Introduction

ROQ provides a complete solution for the management of public and private files. Please read the files feature guide for all information.

Mutations

uploadFile()

This method can be used when you want to upload files directly from your backend file system to your ROQ file storage.

  const file = fs.readFileSync("./roq.png");
  const r = await roqClient.asSuperAdmin().uploadFile({
    fileInfo: {
      file,
      contentType: "image/png",
      name: `roq.png`,
      fileCategory: "USER_FILES",
    },
    options: {
      isPublic: true,
    },
  });

To upload a file using a user account, the function asUser(userId) requires a user id. There are multiple methods to retrieve the user ID, such as utilizing GraphQL:

query users(
  $limit: Int = 10,
  $offset: Int = 0,
) {
  users(
    limit: $limit,
    offset: $offset,
  ) {
    totalCount
    data {
      id
      email
    }
  }
}

updateFile()

You can use the updateFile() API to rename the uploaded files. Visit the API documentation here (opens in a new tab).

const updateResult = await roqClient.asSuperAdmin().updateFile({
	id: "97eeb4da-d402-4a89-b034-bcb277b9e65c",
	updateFileDto: {
		name: "screenshot.png"
	}
})

updateFileStatus()

The updateFileStatus() API is a method to set the upload file status. The use case of this API is, for example, you upload a file without using UI Component, and after the file upload is completed, you need to set the upload file status manually.

Five status files are currently available: cancelled, error, processing, ready, and upload_pending.

const upfileStatus = await roqClient.asSuperAdmin().updateFileStatus({
	id: "97eeb4da-d402-4a89-b034-bcb277b9e65c",
	status: FileStatusEnum.Cancelled
})

createFileUpload()

To upload a file via API, you need to proceed with the following steps:

await client.asSuperAdmin().createFileUpload({
  createFileDto: {
    name: 'abc123',
    contentType: 'image/png',
    fileCategory: 'xyz789',
  }
});

curl \
-F "<formFieldsKey1>=<formFieldsValue1>" \
-F "<formFieldsKey2>=<formFieldsValue2>" \
-F "file=@<file-path-from-local>" \
  <upload-url-from-response>

await client.asSuperAdmin().updateFileStatus({
  id: '123',
  status: 'READY',
});

deleteFiles()

To delete one or multiple files, use the deleteFiles() API. See this link (opens in a new tab) for the API documentation.

const delFiles = await roqClient.asSuperAdmin().deleteFiles({
	filter: {
		id: {
			equalTo: "76dada4e-4f07-456b-90e7-a43099f07052"
		}
	}
})

{
  filter: {
    id: {
      valueIn: ["file_id_1", "file_id_2"]
    }
  }
}

createFileAssociation()

Files usually belong to some other object. For instance, you may have PDFs which represent "contracts". Or you may have images which are "avatars" and so on. To simplify this, ROQ enables you to relate files with objects which are saved on your database. The advantage is that you don't need to add these relations to your own database. File associations will simplify the database schema.

await client.asSuperAdmin().createFileAssociation({
  createFileAssociationDto: {
    entityName: "purchase_history",
		entityReference: "3c0e2ce1-3105-447a-b214-ac1e0b1e7304",
		fileId: "97eeb4da-d402-4a89-b034-bcb277b9e65c"
  },
});

deleteFileAssociations()

Using this API will result in the deletion of any file associations. If you require more information, please refer to the API documentation (opens in a new tab).

const delFileAssoc = await roqClient.asSuperAdmin().deleteFileAssociations({
	filter: {
		id: {
			equalTo: "7526d4b4-26db-4872-834d-68da2a1447e9"
		}
	}
})

makeFilePublic()

To enable public access to a file, run:

await client.asSuperAdmin().makeFilePublic({
  id: 'fileId',
});

makeFilePrivate()

To hide a file from public access, you can execute:

await client.asSuperAdmin().makeFilePrivate({
  id: 'fileId',
});

Queries

files()

You can get a list of files using the files() query, and you can read the API documentation here (opens in a new tab).

Access management: The query returns all files that are accessible for the current user.

Associations: You can use the filters to find files which are associated with other objects; see createFileAssociation(). The typical flow looks like this: First, you fetch the ID of an object from your database and then query the related files. For instance, the query shown below requests all files that are associated with a specific "contract".

Visibility: For files marked as “public”, the returned URL is static. If the file is marked as “private”, then the URL is referred to as a signed URL, which is created for only one purpose. A signed URL works only for a short amount of time and is not intended to be published.

await roqClient.asSuperAdmin().files({ filter: {
  entityName: { equalTo: "contract" },
  entityIdentifiers: { equalTo: "123" },
  fileCategory: {
    key: {
      equalTo: "CHAT_FILES"
    }
  }
}});

file()

You can use the file() query to download a single file. This API method will return all the file data, such as the URL, file category, who created it, or the file associations. The API documentation is here (opens in a new tab).

await client.asSuperAdmin().file({ id: "a1db443e-5726-4c15-873a-2643e34fa7f2"});

fileCategories()

With this fileCategories() API method, we can get all the available file categories. This category can be used to upload files or filter files. For API documentation, visit here (opens in a new tab).

const cats = await roqClient.asSuperAdmin().fileCategories({
	withFileCategoryContentGroups: true
})

fileCategory()

This API method will give detailed data about a file category. The API documentation can be found here (opens in a new tab).

const fileCategoryData = await roqClient.asSuperAdmin().fileCategory({ 
  id: "76dada4e-4f07-456b-90e7-a43099f07052" 
});