Each resource element has the following attributes:

• name: The name of the resource.
• tag: The unique tag of the resource (the tracked HTTP ETag value for that resource).
• type: The mime-type of a file-resource.
• access: If the include-access request parameter is true, this attribute contains the allowed operations for the current user (comma-separated). Possible operations are read, write and delete.
• deleted: Whether this is a (recently) deleted resource or not. If this attribute is absent, the default is false.
• directory: Whether the resource is a directory or not. Default is false.
• size: The size (in bytes) of a file-resource.
• last-modified: When the resource was last touched. A directory is not touched when its contents are changed.
• md5: The md5 hash of a file-resource.
• blob: If the include-blob-uuid request parameter is true, this attribute contains the blob UUID of a file-resource.

Note

Stores only keep track of the deleted state of a resource for a certain amount of time, after which the resource is no longer marked as deleted. In this case they are no longer part of directory listings. Some store implementations do not track ETag values or deleted state. ETag values of ancestors are no longer required to change when a change occurs on a descendant resource.

Each store element has the following attributes:

• name: The name of the resource.
• tag: The unique tag of the resource (the tracked HTTP ETag value for that resource).
• deleted: Whether this is a (recently) deleted resource or not. Default is false.
• directory: Whether the resource is a directory or not. Default is false.

The store-features element lists the features supported by a store and can be used by clients to determine how they should interact with the store. The following is a list of available features:

• sync: Indicates whether the store supports the ability for clients to sync its contents.
• sync-recursive: Indicates that the store supports the recursive sync type. Stores with this feature guarantee that the ETag of a directory changes if any resource below it is created, updated or deleted. This allows clients to recursively check their local data against the server and skip directories for which the ETag has not changed.
• sync-snapshot: Indicates that the store supports the snapshot sync type. Stores with this feature will not change the ETag of a directory if any resource below it is created, updated or deleted. Clients that want to sync with stores that support this feature should retrieve a full listing for the path they want to sync by specifying the recursive query parameter when retrieving a directory listing.

Change events is a plaintext resource that contains events separated by newlines that have occurred on the stores. The structure of most events is as follows (the text between braces is replaced by an actual value):

CHANGE|{event ID}|{IDR URI}|{operation}|{previous ETag}|{new ETag}|{type}

• {event ID} an event ID, this will be unique within the same store.
• {IDR Location} the IDR URI of the change. This URI thus contains the store and path of the resource that changed.
• {operation} the operation that occurred can be one of the following: modify or delete.
• {previous ETag} the previous ETAG of the resource, can be empty.
• {new ETag} the new ETAG of the resource.
• {type} the type of the resource, can be empty.

Useful client applications that use events are:

• Monitor certain stores and paths for changes, and act upon this.
• To implement a mirror of the resource store or a subtree of a store. By replaying the events on its local copy it remains in sync with the remote. This removes the need for a complex and resource intensive synchronization algorithm.

To implement a client that monitors for changes on the resource server, perform the following steps.

• The client makes an initial request without query parameter.
• The server responds with the current event status of all its stores. The client is required to maintain a mapping from a store it is interested in to that store’s most recent event.

• The client is now able to send requests and may fill in query parameters based on the mapping from store to event that has been created in the previous step. Upon receiving this request from the client, the server responds with one of the following response codes:

  • Status 200 when new events occur or have occurred since the provided events.

  • The server will reply with a status 204 if no events occurred within 30 seconds after the connection was made.

  • If the server no longer knows the provided event for a provided store it sends back a reset. This may happen as the server only keeps events for a limited amount of time.

    RESET

    {store name}

    {event id}

  This message tells the client to reset its algorithm for this store and restart from the specified event.

  Note

  This means that the client might need to perform extra work to make sure that the resources are up to date. This can be done by using, for instance, a recursive listing to check that the client’s state is still in sync with that of the server.

• Based on the server’s response, the client must update the mapping it keeps from stores to events and send the next request.