Files API

Introduction

ROQ provides a complete solution for 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
    }
  }
}

createFileUpload()

To upload file via API you need to proceed 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',
});

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.

await client.asSuperAdmin().createFileAssociation({
  createFileAssociationDto: {
    entityReference: 'reference',
    entityName: 'xyz789',
    fileId: '4',
  },
});

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.

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 loke 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 client.asSuperAdmin().files({ filter: {
  entityName: { equalTo: "contract" },
  entityIdentifiers: { equalTo: "123" }
}});

file()

To download a single file, you can use the file() query.

await client.asSuperAdmin().file({ id: "849384FileIMG"});