In order to use the REST Interface, it's important to understand some things about the underlying object model and architecture that are not necessarily apparent when using the Filr web, desktop or mobile applications. Filr is built on the same architecture as Novell Vibe. While not so visible in the end-user Filr applications, some of the Vibe-isms appear in the REST interface.
Filr consists of a hierarchy of workspaces and folders. The top level of this hierarchy is a workspace called “Home Workspace”. It has two child workspaces that are relevant to Filr:
Personal Workspaces: Each Filr user has a workspace in this location containing the user's personal storage and link to the user's home directory.
Net Folders: This workspace contains the Net Folder references that the has configured.
The top level folders that users see when logging into Filr (such as My Files, Shared with Me and Net Folders) do not exist in this workspace hierarchy. They are virtual views where files and folders are aggregated from different parts of the Filr workspace hierarchy.
Together, workspaces and folders are known as binders. That is, a binder is a generic container that can have children. A workspace is a binder that can contain other workspaces and also folders. A folder is a binder that can contain other folders and also folder entries (see below).
Files are represented in Filr as a folder entry with a single attachment. The attachment contains important metadata about the file itself, such as the size, last modification time and file name. The folder entry contains the Filr-related information, such as the location in the folder/workspace hierarchy and information about sharing and comments.
The REST interface tries to blend the folder entry and attachment into a single object called FileProperties where possible, but when developing a REST client, it's still important to understand that it really is a folder entry with an attachment in the underlying architecture.
A Reply represents a user comment on a file. In the underlying architecture, it's actually a folder entry, but the REST interface treats it as a separate type of object. The text of the user's comment is contained in the description property of the reply object.
A user can reply to the folder entry (the file) or to another reply. So, a reply has a parent entry, which can either be a folder entry or another reply. It also has a top entry, which is always a folder entry.
Users and Groups (Principals)
Together, users and groups are known as principals.
In Vibe, there are a number of different types of folders. Some folder types mirror file system folders and require that files in the folder have unique file names. Others do not have this same requirement. Those folders that require unique file names are called “library folders”.
In Filr, all folders require unique file names and are therefore “library folders”. This is only important for Filr developers to understand because the term “library” appears throughout the Filr REST interface.