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,
    },
  });

createFileUpload()

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

1. Generate a signed URL using the createFileUpload() API
2. Upload file via the signed URL
3. Set status of the file using the updateFileStatus() API

(1) Generate a signed URL

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

mutation {
  createFileUpload(
    file: { name: "abc123", contentType: "image/png", fileCategory: "xyz789" }
  ) {
    id
    uploadUrl
    formFields
  }
}

(2) Upload file via the signed URL

With the returned URL you can upload the file, for instance using curl:

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

(3) Set status of the file

When the upload is finished, you need to set the status of the upload. This is needed because the file is uploaded directly to the object storage and therefore bypasses ROQ Platform.

mutation {
  updateFileStatus(fileId: "123", status: READY) {
    id
  }
}

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.

mutation {
  createFileAssociation(
    createFileAssociationDto: {
      entityReference: "reference"
      entityName: "xyz789"
      fileId: "4"
    }
  ) {
    id
  }
}

makeFilePublic()

To enable public access to a file, run:

mutation makeFilePublic($fileId: ID!) {
  makeFilePublic(id: $fileId) {
    id
  }
}

makeFilePrivate()

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

mutation makeFilePrivate($fileId: ID!) {
  makeFilePrivate(id: $fileId) {
    id
  }
}

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.

query {
  files(
    filter: {
      entityName: { equalTo: "contract" }
      entityIdentifiers: { equalTo: "123" }
    }
  ) {
    data {
      id
      name
      contentType
      url
      isPublic
    }
  }
}

file()

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

query {
  file(fileId: "123") {
    id
    name
    url
    isPublic
  }
}