API

File uploading

`createFileUpload()`

Generate a signed URL using the createFileUpload() API. The API returns a signed URL, which is then used to upload the file directly from the user's browser to the object storage.

await roqBrowserClient.roqPlatform.createFileUpload({
    data: {
        name: file.name,
        contentType: file.type,
        fileCategory: 'USER_FILES',
    }
})

Parameter	Type	Description
`name`	string	Name of the uploaded file
`contentType`	string	Mime type of the file, see here (opens in a new tab) for a list of all types
`fileCategory`	string	`Key` of the category of the file

File reading

This pertains to accessing and retrieving data from the uploaded files.

`files()`

Get all files.

import { roqBrowserClient } from 'lib/roq/roq-client';
 
const allFiles = async () => {
	const allFiles = await roqBrowserClient.roqPlatform.files()
	return allFiles
}

Parameter	Type	Description
`limit`	integer	The number of files to return.
`offset`	integer	The offset number of files.
`order`	object	The order of the files.
`filter:entityName`	object	Name of the object. This could be the name of the table in your database, e.g. "contract".
`filter:entityReferences`	object	References (or IDs) of the related objects from your database.
`filter:fileCategory`	object	Filter file by categories.
`withFileCategory`	boolean	Include file categories
`withCreatedByUser`	boolean	Include user data that created the file
`withFileAssociations`	boolean	Include file associations

`file()`

Get file with specific file ID.

The file() API also provides information on the file category, its creator, and associations.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const myfile = async () => {
	const myfile = await roqBrowserClient.roqPlatform.file({
		id: "e54b7785-f7c0-41cc-bfbe-06dbd1645ed9",
		withFileCategory: true,
		withCreatedByUser: true,
		withFileAssociations: true
	})
}

Parameter	Type	Description
`id`	UUID	The file ID
`withFileCategory`	boolean	Include file category
`withCreatedByUser`	boolean	The user that create the file
`withFileAssociations`	boolean	Include file associations

File updating

`updateFile()`

You can use the updateFile() API to rename the uploaded files.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const updateResult =async () => {
    return await roqBrowserClient.roqPlatform.updateFile({
        data: {
            fileId: "97eeb4da-d402-4a89-b034-bcb277b9e65c",
            name: "screenshot.png",
            status: FileStatusEnum.Ready
        }
    })
}

Parameter	Type	Description
`data:fileId`	UUID	The file ID to be updated.
`data:name`	string	New filename.
`data:status`	string	The file status.

File deletion

`deleteFiles()`

To delete one or multiple files, use the deleteFiles() API.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const delFiles =async () => {
    return await roqBrowserClient.asSuperAdmin().deleteFiles({
	    filter: {
		    id: {
			    equalTo: "76dada4e-4f07-456b-90e7-a43099f07052"
		    }
	    }
    })
}

To delete multiple files, utilize the valueIn filter option.

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

Parameter	Type	Description
`filter:id`	object	The IDs of files to delete can be filtered using `equalTo` for a single file or `valueIn` for multiple file IDs.

File categories

File categories can be managed via API or ROQ Console.

Using the fileCategories() and fileCategory() APIs from the ROQ Platform, we can retrieve a list of all registered file categories and their details, respectively. These APIs can be easily used on the client-side via front-end SDK.

`fileCategories()`

Get all file categories.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const doReadCategories = async () => {
	const allCategories = await roqBrowserClient.roqPlatform.fileCategories({})
	return allCategories
}

Parameter	Type	Description
`limit`	integer	Limit the results
`search`	object	Search parameter
`filter`	object	Filter parameter
`offset`	integer	Offset the results
`order`	object	Order parameter

`fileCategory()`

Get file category details.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const categoryDetails = async () => {
	const categoryDetail = await roqBrowserClient.roqPlatform.fileCategory({
		id: "ff8143f2-cd89-41e9-af16-999c9b9da9b8",
		withFileCategoryContentGroups: true
	})
	return categoryDetail
}

Parameter	Type	Description
`id`	UUID	The file category ID to be retrieved.
`withFileCategoryContentGroups`	boolean	Include file category content groups.

File visibility

A file can be either public or private. Public means that there is a permanent URL that anyone can use, while private files can only be accessed by users who are allowed to do so. The visibility of a file can be changed in ROQ Console or API using the makeFilePrivate() and makeFilePublic(). These APIs also can be easily used on the client-side via front-end SDK.

`makeFilePublic()`

Enable public access to a file.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const roqBrowserClient = useroqBrowserClient()
 
const filePublic =async () => {
    return await roqBrowserClient.roqPlatform.makeFilePublic({
        id: 'fileId'
    });
}

Parameter	Type	Description
`id`	UUID	The file ID to be made public.

`makeFilePrivate()`

Hide a file from public access.

import { roqBrowserClient } from "lib/roq/roq-client"
 
const roqBrowserClient = useroqBrowserClient()
 
cons private =async () => {
    return await roqBrowserClient.roqPlatform.makeFilePrivate({
        id: 'fileId'
    })
}

Parameter	Type	Description
`id`	UUID	The file ID to be made private.

File associations

ℹ️

This endpoint is only available from the server side of your application.

`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 roqServerClient.roqPlatform.asSuperAdmin().createFileAssociation({
    data: {
        entityName: "purchase_history",
		entityReference: "3c0e2ce1-3105-447a-b214-ac1e0b1e7304",
		fileId: "97eeb4da-d402-4a89-b034-bcb277b9e65c"
  },
});

Parameter	Type	Description
`fileId`	UUID	The ID of the file
`entityReference`	UUID	Reference (or ID) of the related entity in your database
`entityName`	string	Name of the object. This could be the name of the table in your database, e.g. "purchase_history"

`deleteFileAssociations()`

Using this API will result in the deletion of any file associations.

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

Parameter	Type	Description
`filter:id`	object	You can use `equalTo` or `valueIn` for the ID of the file associations
`filter:fileId`	object	You can use `equalTo` or `valueIn` for the ID of the files

Overview Uploading Files