Skip to main content

Files

Organize data in content objects as file and directory structure.

Creation / Modification​

  1. Create a Files Job and submit the list of files that will be uploaded in one or multiple batch requests. For each file, its path, exact size and optional metadata (e.g. mime type) are specified.

    The fabric automatically maps files to parts in order to optimize part storage: small files are aggregated into a single part, large files are split across multiple parts. For each part, an Upload Job is returned that contains the list of files or file segments that are to be uploaded in order.

    Adding files is only one of multiple operations that can be specified in a Files Job: files can also be deleted, moved, copied, or their metadata updated. As these additional operations apply to existing files in the content object, they only make sense when creating new versions of existing content objects or when modifying a previous Files Job.

  2. Upload file data according to the generated upload jobs. For improved performance, upload jobs may be performed in parallel.

    In case of upload failures, retrieve the status of the corresponding upload job to find out at which position the upload should be resumed.

  3. Once all data is uploaded, finalize the files. The fabric will by check that all necessary file data has been uploaded and will optimize the file metadata structures.

Reading File Metadata​

Example file metadata:

{
  "files" : {
    ".": {
      "type": "directory"
    },
    "html": {
      ".": {
        "type": "directory"
      },
      "index.html": {
        ".": {
          "mime_type": "text/html",
          "parts": [ 0 ],
          "size": 3144
        }
      }
    },
    "images": {
      ".": {
        "type": "directory"
      },
      "logo.png": {
        ".": {
          "parts": [ 1 ],
          "size": 46943
        }
      }
    }
  }
}

The directory structure and file information is stored as regular metadata of the content object under the files key. Each item (directory or file) is stored as an object labelled with its name and using an embedded . key to store the item's metadata like type (file or directory), size, mime-type, etc.

Downloading Files​

The files API provides a download endpoint for retrieving a file identified by its path. It supports the standard HTTP Range header to retrieve partial files.

The file hierarchy supports symbolic links to other files or directories similar to a Unix filesystem. Links are created in a Files Job (just like regular files), but obviously don't require a subsequent data upload, since they merely point to another file or directory.

File links may be relative, pointing to other files or directories within the same content object, or absolute by targeting an entry in another content object. See file links for details.