Folders

The Folders API provides an organizational structure for SAS and external content. It can also be used for favorites folders or a history of objects accessed. The resources that are stored in folders (members) use a URI to point back to those resources.

Table of Contents generated with DocToc

The Folders API is used to create a virtual folder hierarchy for organizing and presenting resources. There is no physical backing structure, such as a file system, DAV, or JCR. The Folders API persists only the URI of resources that are managed by other persistence services. In general, the persistence services and the Folders API do not know about each other. The persistence services that own the resources that are members of the folders know nothing directly about the Folders API, and the Folders API knows nothing of the persistence services. This design maintains the loose coupling that is a fundamental concept of the microservices architecture.

There are two exceptions where a persistence service and the Folders service know about each other:

  • The persistence service knows about the Folders service when the persistence service is creating a new object. The persistence service might implement the Creating objects in folders as a single transaction pattern, which accepts a parentFolderURI query parameter and makes a call to the Folders API to add the new object to the specified folder as a child member. If the member creation fails, the persistence service cleans up the newly created resource and returns a proper response that indicates why the member could not be created.

  • The exception to the Folders API knowing about the persistence service is the event consumer. The Folders API listens for change events (for example, an UPDATE or DELETE). If an object that is a child of a folder changes, it tries to retrieve the summary (application/vnd.sas.summary) representation of the object and, if successful, updates the object's name, description, and modified time stamp. The summary type should normally be recognized by content persistence services. If the persistence service does not answer to the summary media type, or if any other error occurs, the member is not updated. If the persistence service does not allow automatic updating by the folders service, a client uses the PUT operation to update members with changes in the content.

Folder Types to Specify for the Type Field

There are three types of folders you can use in the type field:

  • folder - This is just a basic folder, with no particular restrictions. If the type is not specified, this is the default value.

  • favoritesFolder - This type of folder can hold only reference members, or other favoritesFolders. Attempting to add a child of any other type results in an error response.

  • historyFolder - This type of folder can contain only references. The folder has a property of "maxMembers" that limits the number of members the folder can hold. The default value of maxMembers is 40. When maxMembers is reached, members are evicted when a new member is added following this policy: 1) the member with the highest value of OrderNum and 2) the member with the oldest time stamp. History folders respond to some special endpoints under the /folders/{folderId}/histories path. These endpoints provide special behavior when adding or updating history entries. A POST to /folders/{folderId}/histories "touches" the entry. That is, a POST creates a history entry if it is not there or updates the history entry's data, including the added attribute, if it already exists (based on an exact match of the uri field).

Folder Types That Are Returned When Creating a Folder

These three special folder types are returned and cannot be specified when creating a folder.

  • userFolder - One folder of this type is created per user, named for the user's user name. This folder is the parent of the other special folders.

  • myFolder - Users have one folder of this type for storing items that they do not want to share with other users. Items in this folder are not visible to other users except administrative users.

  • applicationDataFolder - This folder is used by applications to store data specific to one user.

All GET operations have a corresponding HEAD with identical signature and semantics except the resource body is not returned.

Rules for Folders and Folder Members

Folders are not managed on a per-user basis. In other words, in general, folders are intended to be shared by some group of users. The exception is the user folder and the special folders that are stored under the user folder (myFolder, appDataFolder, myHistory, and myFavorites). Those folders are intended solely for the use of the user for which they were created. Authorizations are created to enforce that level of access.

There are two types of folder members: child and reference. A given resource URI can exist as a child in only one folder. An attempt to create a child member with the same URI in a second folder results in a 412 response (precondition failed). If it is already in the same parent folder, a 409 response (conflict) is returned. A resource URI can exist as a reference member in as many folders as desired. When an attempt is made to delete a folder, only child members are considered when testing whether the folder is empty. Likewise, only child members are considered when retrieving ancestors.