File Management Service

Access info

Usage

The File Management Service enables managing files in the cloud (create, update, delete). You can create the file content either by downloading it from a publicly accessible URI or by uploading the file content separately through an HTTP PUT method.

Files can be publicly accessible or protected. In case of protected files, you can generate a temporary download URL that will expire after a custom number of seconds.

The API also provides the ability to filter records, and add custom file attributes.

Creating files

Creating new files is a two-step operation. First, run the createFile mutation and specify the file name to be created as input, for example:

mutation create_file($input:CreateFileInput) {
  createFile(input: $input) {
    id
    uploadUrl(expiresIn:3600)
  }
}

{
  "input": {
    "name": "info.pdf"
  }
}

The mutation above creates a file and returns the file’s upload URL. The latter is required for the next step. Note that the period after which the upload URL will expire can be parameterized according to your needs. In the mutation above, it is 3600 seconds (1 hour).

Secondly, run an HTTP PUT request and upload the actual file bytes to the upload URL. The exact program code to achieve this depends on the language you are using. With cURL, the upload operation looks as follows:

• If you have a bash terminal, run:
  Copy

  curl --location --request PUT 'YOUR_UPLOAD_URL' --header 'Content-Type: application/pdf' --data-binary '@/path/to/your/file.pdf'
  

• If you have a Windows terminal, run:
  Copy

  curl --location --request PUT "YOUR_UPLOAD_URL" --header "Content-Type: application/pdf" --data-binary "@C:\file.pdf"
  

For a more detailed example, see the Tutorial: Create a file.

Renaming files

To rename a file, run the updateFile mutation. You will need to supply as input the file ID and the new file name (with extension), for example:

mutation($input:UpdateFileInput) {
  updateFile(input: $input) {
    name
  }
}

{
  "input": {
    "id": "YOUR_FILE_ID",
    "name": "renamedFile.txt"
  }
}

Updating files

You can update existing files by issuing a new HTTP PUT request to the file’s upload URL, with the new file bytes in the payload of the request. To obtain the file’s upload URL, run the files query and make sure to set the URL’s expiry timeout to a suitable value for your needs, for example:

query($filter:FilesFilter, $uploadUrlTimeout:Int) {
  files(filter:$filter){
    items {
      id
      name
      status
      uploadUrl(expiresIn: $uploadUrlTimeout)
    }
  }
}

{
  "filter": {
    "id": "YOUR_FILE_ID"
  },
  "uploadUrlTimeout": 3600
}

While the upload URI is still valid, run an HTTP PUT request to replace the file content. This request looks like the one illustrated above for creating new files.

Note that you can change the actual file’s bytes but you cannot change the file content (MIME) type (for example, from text to PDF). To achieve that, you will need to create a new file.

Deleting files

To delete a file, run the deleteFile mutation. You will need to supply as input the file ID of the file to be deleted, for example:

mutation delete_file($id: String) {
  deleteFile(id: $id) {
    id
  }
}

{
    "id": "YOUR_FILE_ID"
}

Uploading large files

When you need to upload large files exceeding 100 MB, you should consider the multipart upload. This means uploading the file in smaller chunks, rather than performing the upload as one operation. To perform a multipart upload, the API provides dedicated mutations. More precisely, the steps for uploading a large file are as follows:

1. Programmatically split the file into several file parts (byte arrays). Each part must be larger than 5 MB and less than 5 GB. There is no minimum size limit on the last part.
2. Call initiateMultipartUpload to obtain a unique identifier of the upload.
3. For each individual part, call generatePartUploadUrl to get its upload URL.
4. To upload each individual part, send a PUT request at the obtained upload URL. When parts are uploaded, the response contains an ETag header. This value will be required in the completeMultipartUpload mutation.
5. Run the completeMultipartUpload mutation to assemble the uploaded file parts back into the original file.

For an example, see the Tutorial: Upload a large file.

“Content-Disposition” header

Except for files to which you haven’t uploaded any content yet, all files created through the File Management Service have a download URL. When any browser or HTTP client accesses the URL, the HTTP response is by default without a Content-Disposition Header. This means the browser does not have a clear indication on whether to open the download URL inline (that is, directly in the browser window) or as an attachment. You can optionally set the Content-Disposition header (and thus define explicitly how the browser should treat the download URL) by adding this header to the HTTP PUT request when you upload the file content.

For example, setting the Content-Disposition header as follows:

Content-Disposition: attachment; filename="start.jpg"

will indicate to the browser (when downloading the file) that the file is a downloadable resource, and also provide a hint that the suggested file name for saving is “start.jpg”.

Queries

file

Retrieve information about a single file, by file ID.

Arguments

Result

See the File type.

files

Lists files from the cloud, according to the filter criteria provided as input.

Arguments

FilesFilter input

Result

FilesResult type

File type

Author type

FileStatus enum

Error type

Attribute type

filesWithExternalReference

Lists only files having the externalReference attribute supplied as input.

Arguments

FilesWithExternalReferenceFilter input

Result

An array of objects of File type.

version

Returns the API version.

Mutations

createFile

Creates a file in the cloud. Depending on the input arguments, the file content is either empty or populated from some URI.

Arguments

CreateFileInput input

AuthorInput input

AttributeInput input

Result

File type

See the File type.

completeMultipartUpload

This mutation is useful when uploading large files, through a multipart upload. It completes the multipart upload operation, by assembling the already uploaded file parts back into a file. Run this mutation only after you have run the initiateMultipartUpload and generatePartUploadUrl mutations.

Arguments

completeMultipartUploadInput input

PartETag input

Result

File type

See the File type.

deleteFile

Arguments

Result

File type

See the File type.

generatePartUploadUrl

This mutation is useful when uploading large files, through a multipart upload. It returns an upload URL at which a file part can be uploaded. Run this mutation only after you have run the initiateMultipartUpload and have obtained an upload ID as a result. This mutation must be run as many times as there are file parts.

Arguments

generatePartUploadUrlInput input

Result

The result is a string that contains the generated upload URL.

initiateMultipartUpload

Initiates a multipart upload of the file. This mutation is the first one in the series of mutations required to upload a large file. It returns an upload identifier that is to be subsequently used in generatePartUploadUrl and completeMultipartUpload mutations.

Arguments

initiateMultipartUploadInput input

Result

MultipartUpload type

updateFile

Arguments

UpdateFileInput input

Result

File type

See the File type.