Tobias.friedrich: /* edit */

<div class="title">OX Drive API</div>

__TOC__

= Introduction =

The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side.

The synchronization is based on checksums for files and folders, differences between the server- and client-side are determined using a three-way comparison of server, client and previously acknowledged file- and directory-versions. The synchronization logic is performed by the server, who instructs the client with a set of actions that should be executed in order to come to a synchronized state.

Therefore, the client takes a snapshot of it's local files and directories, calculates their checksums, and sends them as a list to the server, along with a list of previously acknowledged checksums. The server takes a similar snapshot of the files and directories on the underlying file storages and evaluates which further actions are necessary for synchronization. After executing the server-side actions, the client receives a list of actions that should be executed on the client-side. These steps are repeated until the server-state matches the client-state.

Key concept is that the synchronization works stateless, i.e. it can be interrupted and restarted at any time, following the eventual consistency model.

Entry point for the synchronization is the [[#Synchronize_folders|<code>syncfolders</code>]] request, where the directories are compared, and further actions are determined by the server, amongst others actions to synchronize the files in a specific directory using the [[#Synchronize_files_in_a_folder|<code>syncfiles</code>]] request. After executing the actions, the client should send another <code>syncfolders</code> request to the server and execute the returned actions (if present), or finish the synchronization if there are no more actions to execute. In pseudo-code, the synchronization routine could be implemented as follows:

WHILE TRUE
{
response = SYNCFOLDERS()
IF 0 == response.actions.length
BREAK
ELSE
EXECUTE(response.actions)
}

Basically, it's up to the client how often such a synchronization cycle is initiated. For example, he could start a new synchronization cycle after a fixed interval, if he recognizes that the client directories have changed, or if he is informed that something has changed on the server by an event. It's also up to the client to interrupt the synchronization cycle at any time during execution of the actions and continue later on, however, it's recommended to start a new synchronization cycle each time to avoid possibly outdated actions.

= API =

As part of the [[HTTP_API|HTTP API]], the basic conventions for exchanging messages described there are also valid for this case, especially the [[HTTP_API#Low_level_protocol|low level protocol]] and [[HTTP_API#Error_handling|error handling]]. Each request against the Drive API assumes a valid server session that is uniquely identified by the session id and the corresponding cookies and are sent with each request. A new session can be created via the [[HTTP_API#Module_.22login.22|login module]].

The root folder plays another important role for the message exchange. The root folder has a unique identifier. It is the parent server folder for the synchronization. All path details for directories and files are relative to this folder. This folder's id is sent with each request. To select the root folder during initial client configuration, the client may get a list of synchronizable folders with the [[#Get_synchronizable_Folders|<code>subfolders</code>]] action.

Subsequently all transferred objects and all possible actions are listed.

== File Version ==

A file in a directory is uniquely identified by its filename and the checksum of its content.

{| id="FileVersion" cellspacing="0" border="1"
|+ align="bottom" | File Version
! Name !! Type !! Value
|-
| name || String || The name of the file, including its extension, e.g. <code>test.doc</code>.
|-
| checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

== Directory Version ==

A directory is uniquely identified by its full path, relative to the root folder, and the checksum of its content.

{| id="DirectoryVersion" cellspacing="0" border="1"
|+ align="bottom" | Directory Version
! Name !! Type !! Value
|-
| path || String || The path of the directory, including the directory's name, relative to the root folder, e.g. <code>/sub/test/letters</code>.
|-
| checksum || String || The MD5 hash of the directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

Note: the checksum of a directory is calculated based on its contents in the following algorithm:

* Build a list containing each file in the directory (not including subfolders or files in subfolders)
* Ensure a lexicographically order in the following way:
** Normalize the filename using the <code>NFC</code> normalization form (canonical decomposition, followed by canonical composition) - see http://www.unicode.org/reports/tr15/tr15-23.html for details
** Encode the filename to an array of UTF-8 unsigned bytes (array of codepoints)
** Compare the filename (encoded as byte array "fn1") to another one "fn2" using the following comparator algorithm:

min_length = MIN(LENGTH(fn1), LENGTH(fn2))
FOR i = 0; i < min_length; i++
{
result = fn1[i] - fn2[i]
IF 0 != result RETURN result
}
RETURN LENGTH(fn1) - LENGTH(fn2)

* Calculate the aggregated MD5 checksum for the directory based on each file in the ordered list:
** Append the file's NFC-normalized (see above) name, encoded as UTF-8 bytes
** Append the file's MD5 checksum string, encoded as UTF-8 bytes

== Actions ==

All actions are encoded in the following format. Depending on the action type, not all properties may be present.

{| id="Actions" cellspacing="0" border="1"
|+ align="bottom" | Actions
! Name !! Type !! Value
|-
| action || String || The type of action to execute, currently one of <code>acknowledge</code>, <code>edit</code>, <code>download</code>, <code>upload</code>, <code>remove</code>, <code>sync</code>, <code>error</code>.
|-
| version || Object || The (original) file- or directory-version referenced by the action.
|-
| newVersion || Object || The (new) file- or directory-version referenced by the action.
|-
| path || String || The path to the synchronized folder, relative to the root folder.
|-
| root || String || The corresponding root folder identifier (optional, available since API version 5).
|-
| offset || Number || The requested start offset in bytes for file uploads.
|-
| totalLength || Number || The total length in bytes for file downloads.
|-
| contentType || String || The file's content type for downloads (deprecated, available until API version 2).
|-
| created || Timestamp || The file's creation time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| error || Object || The error object in case of synchronization errors.
|-
| quarantine || Boolean || The flag to indicate whether versions need to be excluded from synchronization.
|-
| reset || Boolean || The flag to indicate whether locally stored checksums should be invalidated.
|-
| stop || Boolean || The flag to signal that the client should stop the current synchronizsation cycle.
|-
| acknowledge || Boolean || The flag to signal if the client should not update it's stored checksums when performing an <code>EDIT</code> action.
|-
| thumbnailLink || String || A direct link to a small thumbnail image of the file if available (deprecated, available until API version 2).
|-
| previewLink || String || A direct link to a medium-sized preview image of the file if available (deprecated, available until API version 2).
|-
| directLink || String || A direct link to the detail view of the file in the web interface (deprecated, available until API version 2).
|-
| directLinkFragments || String || The fragments part of the direct link (deprecated, available until API version 2).
|}

The following list gives an overview about the used action types:

=== <code>acknowledge</code> ===
Acknowledges the successful synchronization of a file- or directory version, i.e., the client should treat the version as synchronized by updating the corresponding entry in its metadata store and including this updated information in all following <code>originalVersions</code> arrays of the <code>syncfiles</code> / <code>syncfolders</code> actions. Depending on the <code>version</code> and <code>newVersion</code> parameters of the action, the following acknowledge operations should be executed (exemplarily for directory versions, file versions are acknowledged in the same way):

* Example 1: Acknowledge a first time synchronized directory The server sends an <code>acknowledge</code> action where the newly synchronized directory version is encoded in the <code>newVersion</code> parameter. The client should store the version in his local checksum store and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.
{
"action" : "acknowledge",
"newVersion" : {
"path" : "/",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

* Example 2: Acknowledge a synchronized directory after updates The server sends an <code>acknowledge</code> action where the previous directory version is encoded in the <code>version</code>, and the newly synchronized directory in the <code>newVersion</code> parameter. The client should replace any previously stored entries of the directory version in his local checksum store with the updated version, and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.
{
"action" : "acknowledge",
"newVersion" : {
"path" : "/",
"checksum" : "7bb1f1a550e9b9ab4be8a12246f9d5fb"
},
"version" : {
"path" : "/",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

* Example 3: Acknowledge the deletion of a previously synchronized directory The server sends an <code>acknowledge</code> where the <code>newVersion</code> parameter is set to <code>null</code> to acknowledge the deletion of the previously synchronized directory version as found in the <code>version</code> parameter. The client should remove any stored entries for this directory from his local checksum store, and no longer send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests. Note that an acknowledged deletion of a directory implicitly acknowledges the deletion of all contained files and subfolders, too, so the client should also remove those <code>originalVersion</code>s from his local checksum store.
{
"action" : "acknowledge",
"version" : {
"path" : "/test",
"checksum" : "3525d6f28eb8cb30eb61ab7932367c35"
}
}

=== <code>edit</code> ===
Instructs the client to edit a file- or directory version. This is used for move/rename operations. The <code>version</code> parameter is set to the version as sent in the <code>clientVersions</code> array of the preceding <code>syncfiles</code>/<code>syncfolders</code> action. The <code>newVersion</code> contains the new name/path the client should use. Unless the optional boolean parameter <code>acknowledge</code> is set to <code>false</code> an <code>edit</code> action implies that the client updates its known versions store accordingly, i.e. removes the previous entry for <code>version</code> and adds a new entry for <code>newVersion</code>.
When editing a directory version, the client should implicitly take care to create any not exisiting subdirectories in the <code>path</code> of the <code>newVersion</code> parameter.
A concurrent client-side modification of the file/directory version can be detected by the client by comparing the current checksum against the one in the passed <code>newVersion</code> parameter.

* Example 1: Rename a file The server sends an <code>edit</code> action where the source file is encoded in the <code>version</code>, and the target file in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the name found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes.
{
"path" : "/",
"action" : "edit",
"newVersion" : {
"name" : "test_1.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
},
"version" : {
"name" : "test.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
}
}

* Example 2: Move a directory The server sends an <code>edit</code> action where the source directory is encoded in the <code>version</code>, and the target directory in the <code>newVersion</code> parameter. The client should move the directory identified by the <code>version</code> parameter to the path found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the directory in <code>version</code> should be updated, too, to reflect the changes.
{
"action" : "edit",
"newVersion" : {
"path" : "/test2",
"checksum" : "3addd6de801f4a8650c5e089769bdb62"
},
"version" : {
"path" : "/test1/test2",
"checksum" : "3addd6de801f4a8650c5e089769bdb62"
}
}

* Example 3: Rename a conflicting file The server sends an <code>edit</code> action where the original client file is encoded in the <code>version</code>, and the target filename in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the new filename found in the <code>newVersion</code> parameter. If the <code>acknowledge</code> parameter is set to <code>true</code> or is not set, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes, otherwise, as in this example, no changes should be done to the stored checksums.
{
"action" : "edit",
"version" : {
"checksum" : "fade32203220752f1fa0e168889cf289",
"name" : "test.txt"
},
"newVersion" : {
"checksum" : "fade32203220752f1fa0e168889cf289",
"name" : "test (TestDrive).txt"
},
"acknowledge" : false,
"path" : "/"
}

=== <code>download</code> ===
Contains information about a file version the client should download. For updates of existing files, the previous client version is supplied in the <code>version</code> parameter. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>download</code> request. The <code>totalLength</code> parameter is set to the file size in bytes, allowing the client to recognize when a download is finished. Given the supplied checksum, the client may decide on its own if the target file needs to be downloaded from the server, or can be created by copying a file with the same checksum to the target location, e.g. from a trash folder. The file's content type can be retrieved from the <code>contentType</code> parameter, similar to the file's creation and modification times that are availble in the <code>created</code> and <code>modified</code> parameters.

* Example 1: Download a new file The server sends a <code>download</code> action where the file version to download is encoded in the <code>newVersion</code> paramter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>. After downloading, the <code>newVersion</code> should be added to the client's known file versions database.
{
"totalLength" : 536453,
"path" : "/",
"action" : "download",
"newVersion" : {
"name" : "test.pdf",
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"
},
"contentType" : "application/pdf",
"created" : 1375276738232,
"modified" : 1375343720985
}

* Example 2: Download an updated file The server sends a <code>download</code> action where the previous file version is encoded in the <code>version</code>, and the file version to download in the <code>newVersion</code> parameter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>, replacing the previous file. After downloading, the <code>newVersion</code> should be added to the client's known file versions database, replacing an existing entry for the previous <code>version</code>.
{
"totalLength" : 1599431,
"path" : "/",
"action" : "download",
"newVersion" : {
"name" : "test.pdf",
"checksum" : "bb198790904f5a1785d7402b0d8c390e"
},
"contentType" : "application/pdf",
"version" : {
"name" : "test.pdf",
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"
},
"created" : 1375276738232,
"modified" : 1375343720985
}

=== <code>upload</code> ===
Instructs the client to upload a file to the server. For updates of existing files, the previous server version is supplied in the <code>version</code> parameter, and should be used for the following <code>upload</code> request. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>upload</code> request. When resuming a previously partly completed upload, the <code>offset</code> parameter contains the offset in bytes from which the file version should be uploaded by the client. If possible, the client should set the <code>contentType</code> parameter for the uploaded file, otherwise, the content type falls back to <code>application/octet-stream</code>.

=== <code>remove</code> ===
Instructs the client to delete a file or directory version. The <code>version</code> parameter contains the version to delete. A deletion also implies a removal of the corresponding entry in the client's known versions store.
A concurrent client-side modification of the file/directory version can be detected by comparing the current checksum against the one in the passed <code>version</code> parameter.

* Example 1: Remove a file The server sends a <code>remove</code> action where the file to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the file identified by the <code>version</code> parameter. A stored checksum entry for the file in <code>version</code> should be removed, too, to reflect the changes. The <code>newVersion</code> parameter is not set in the action.
{
"path" : "/test2",
"action" : "remove",
"version" : {
"name" : "test.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
}
}

* Example 2: Remove a directory The server sends a <code>remove</code> action where the directory to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the directory identified by the <code>version</code> parameter. A stored checksum entry for the directory in <code>version</code> should be removed, too, to reflect the changes.
{
"action" : "remove",
"version" : {
"path" : "/test1",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

=== <code>sync</code> ===
The client should trigger a synchronization of the files in the directory supplied in the <code>version</code> parameter using the <code>syncfiles</code> request. A <code>sync</code> action implies the client-side creation of the referenced directory if it not yet exists, in case of a new directory on the server.

If the <code>version</code> parameter is not specified, a synchronization of all folders using the <code>syncfolders</code> request should be initiated by the client.

If the <code>reset</code> flag in the <code>SYNC</code> action is set to <code>true</code>, the client should reset his local state before synchronizing the files in the directory. This may happen when the server detects a synchronization cycle, or believes something else is going wrong. Reset means that the client should invalidate any stored original checksums for the directory itself and any contained files, so that they get re-calculated upon the next synchronization. If the <code>reset</code> flag is set in a <code>SYNC</code> action without a apecific directory version, the client should invalidate any stored checksums, so that all file- and directory-versions get re-calculated during the following synchronizations.

* Example 1: Synchronize folder The server sends a <code>sync</code> action with a <code>version</code>. The client should trigger a <code>syncfiles</code> request for the specified folder.
{
"action": "sync",
"version": {
"path": "<folder>",
"checksum": "<md5>"
}
}

* Example 2: Synchronize all folders The server sends a <code>sync</code> action without <code>version</code> (or version is //null//). The client should trigger a <code>syncfolder</code> request, i.e. the client should synchronize all folders.
{
"action": "sync",
"version": null
}

=== <code>error</code> ===
With the <code>error</code> action, file- or directory versions causing a synchronization problem can be identified. The root cause of the error is encoded in the <code>error</code> parameter as described at the [[HTTP_API#Error_handling|HTTP API]].

Basically, there are two scenarios where either the errorneous version affects the synchronization state or not. For example, a file that was deleted at the client without sufficient permissions on the server can just be downloaded again by the client, and afterwards, client and server are in-sync again. On the other hand, e.g. when creating a new file at the client and this file can't be uploaded to the server due to missing permissions, the client is out of sync as long as the file is present. Therefore, the boolean parameter <code>quarantine</code> instructs the client whether the file or directory version must be excluded from the synchronization or not. If it is set to <code>true</code>, the client should exclude the version from the <code>clientVersions</code> array, and indicate the issue to the enduser. However, if the synchronization itself is not affected and the <code>quarantine</code> flag is set to <code>false</code>, the client may still indicate the issue once to the user in the background, e.g. as a balloontip notification.

The client may reset it's quarantined versions on it's own, e.g. if the user decides to "try again", or automatically after a configurable interval.

The server may also decide that further synchronization should be suspended, e.g. in case of repeated synchronization problems. Such a situation is indicated with the parameter <code>stop</code> set to <code>true</code>. In this case, the client should at least cancel the current synchronization cycle. If appropriate, the client should also be put into a 'paused' mode, and the user should be informed accordingly.

There may also be situations where a error or warning is sent to the client, independently of a file- or directory version, e.g. when the client version is outdated and a newer version is available for download.

The most common examples for errors are insufficient permissions or exceeded quota restrictions, see examples below.

* Example 1: Create a file in a read-only folder The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : ["/test"],
"error" : "You are not allowed to create files at \"/test\"",
"error_id" : "1358320776-69",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0012"
},
"path" : "/test",
"quarantine" : true,
"action" : "error",
"newVersion" : {
"name" : "test.txt",
"checksum" : "3f978a5a54cef77fa3a4d3fe9a7047d2"
}
}

* Example 2: Delete a file without sufficient permissions Besides a new <code>download</code> action to restore the locally deleted file again, the server sends an <code>error</code> action where the errorneous file is encoded in the <code>version</code> parameter and the <code>quarantine</code> flag is set to <code>false</code>. Further synchronizations are not affected, but the client may still inform the user about the rejected operation. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : ["test.png", "/test"],
"error" : "You are not allowed to delete the file \"test.png\" at \"/test\"",
"error_id" : "1358320776-74",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0011"
},
"path" : "/test",
"quarantine" : false,
"action" : "error",
"newVersion" : {
"name" : "test.png",
"checksum" : "438f06398ce968afdbb7f4db425aff09"
}
}

* Example 3: Upload a file that exceeds the quota The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : [],
"error" : "The allowed Quota is reached",
"error_id" : "-485491844-918",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0016"
},
"path" : "/",
"quarantine" : true,
"action" : "error",
"newVersion" : {
"name" : "test.txt",
"checksum" : "0ca6033e2a9c2bea1586a2984bf111e6"
}
}

* Example 4: Synchronize with a client where the version is no longer supported. The server sends an <code>error</code> action with code <code>DRV-0028</code> and an appropriate error message. The <code>stop</code> flag is set to <code>true</code> to interrupt the synchronization cycle.
{
"stop" : true,
"error" : {
"category" : 13,
"error_params" : [],
"error" : "The client application you're using is outdated and no longer supported - please upgrade to a newer version.",
"error_id" : "103394512-13",
"categories" : "WARNING",
"code" : "DRV-0028",
"error_desc" : "Client outdated - current: \"0.9.2\", required: \"0.9.10\""
},
"quarantine" : false,
"action" : "error"
}

* Example 5: Synchronize with a client where a new version of the client application is available. The server sends an <code>error</code> action with code <code>DRV-0029</code> and an appropriate error message. The <code>stop</code> flag is set to <code>false</code> to indicate that the synchronization can continue.
{
"stop" : false,
"error" : {
"category" : 13,
"error_params" : [],
"error" : "A newer version of your client application is available for download.",
"error_id" : "103394512-29",
"categories" : "WARNING",
"code" : "DRV-0029",
"error_desc" : "Client update available - current: \"0.9.10\", available: \"0.9.12\""
},
"quarantine" : false,
"action" : "error"
}

== Synchronize folders ==

This request performs the synchronization of all folders, resulting in different actions that should be executed on the client afterwards. This operation typically serves as an entry point for a synchronization cycle.

PUT <code>/ajax/drive?action=syncfolders</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>version</code> - The current client version (matching the pattern <code>^[0-9]+(\\.[0-9]+)*$</code>). If not set, the initial version <code>0</code> is assumed.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request Body: 
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current directories below the root directory as a flat list, encoded as [[#Directory_Version|Directory Versions]]. The original versions array contains all previously known directories, i.e. all previously synchronized and acknowledged directories, also encoded as [[#Directory_Version|Directory Versions]].

Optionally, available since API version 2, the JSON object may also contain two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern|File patterns]] and [[#Directory_pattern|Directory patterns]] accordingly. See [[#Client_side_filtering|Client side filtering]] for details.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}, {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}
],
"originalVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}, {
"path" : "/test2",
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}
]
}

<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"version" : {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}
}
]
}

Example 2:
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}, {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}
],
"originalVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}, {
"path" : "/test2",
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}
]
"fileExclusions" : [{
"path" : "/",
"name" : "excluded.txt",
"type" : "exact"
}
], "directoryExclusions" : [{
"path" : "/temp",
"type" : "exact"
}, {
"path" : "/temp/*",
"type" : "glob"
}
]
}

<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"version" : {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}
}
]
}

== Synchronize files in a folder ==

This request performs the synchronization of a single folder, resulting in different actions that should be executed on the client afterwards. This action is typically executed as result of a <code>syncfolders</code> action.

PUT <code>/ajax/drive?action=syncfiles</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>columns</code> (optional) - A comma-separated list of columns representing additional metadata that is relevant for the client. Each column is specified by a numeric column identifier. Column identifiers for file metadata are defined in [[#FileMetadata|File Metadata]]. If available, the requested metadata of files is included in the corresponding <code>DOWNLOAD</code> and <code>ACKNOWLEDGE</code> actions (deprecated, available until API version 2).
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.
* <code>driveMeta</code> (optional, available since API version 5) - Controls the <code>.drive-meta</code> synchronization mode: <code>true</code>/<code>false</code> to forcibly enable or disable metadata synchronization for the request, or <code>inline</code> to include <code>.drive-meta</code>-data inside a corresponding <code>DOWNLOAD</code> action as <code>data</code>-parameter if suitable.

Request Body: 
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current files in the client directory, encoded as [[#File_Version | File Versions]]. The original versions array contains all previously known files, i.e. all previously synchronized and acknowledged files, also encoded as [[#File_Version | File Versions]].

Optionally, available since API version 2, the JSON object may also contain an array named <code>fileExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern | File patterns]]. See [[#Client_side_filtering|Client side filtering]] for details.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>. If <code>driveMeta</code> was set to <code>inline</code>, <code>DOWNLOAD</code> actions for <code>.drive-meta</code> will carry the metadata in an additional JSON object in the corresponding action's parameters at <code>data</code>, if the <code>.drive-meta</code>-file is smaller than a certain threshold (the contents may still be requested with an explicit download then).

Example:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}, {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
],
"originalVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}
]
}

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
{
"data" : [{
"path" : "/test2",
"action" : "upload",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
},
"offset" : 0
}
]
}

Example 2:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}, {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
],
"originalVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}
]
"fileExclusions" : [{
"path" : "*",
"name" : "*.tmp",
"type" : "glob"
}
]
}

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
{
"data" : [{
"path" : "/test2",
"action" : "upload",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
},
"offset" : 0
}
]
}

Example 3:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=123975&path=/&apiVersion=4&driveMeta=inline&session=0833ca06093a4bad826347a30bf7ace7
> Content:
{
"clientVersions": [],
"originalVersions": []
}

<== HTTP 200 OK (27.5238 ms elapsed, 2058 bytes received)
< Content:
{
"data": {
"actions": [{
"action": "download",
"newVersion": {
"checksum": "36301942a30c3c09bc59f6e9b0c63fba",
"name": ".drive-meta"
},
"totalLength": 1511,
"data": {
"id": "123975",
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"entity": 7,
"group": false
}],
"extended_permissions": [{
"entity": 7,
"bits": 403710016,
"type": "user",
"display_name": "Test User 2",
"contact": {
"email1": "test2@local.ox",
"last_name": "test2",
"first_name": "test2"
}
}],
"jump": ["permissions"],
"shareable": true,
"files": [{
"name": "test1.txt",
"created": 1460030191867,
"modified": 1460030191867,
"created_by": 7,
"modified_by": 7,
"content_type": "text/plain",
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=1600&height=1600",
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"edit",
"permissions",
"version_history"]
},
{
"name": "test2.txt",
"created": 1460030191931,
"modified": 1460030191931,
"created_by": 7,
"modified_by": 7,
"content_type": "text/plain",
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=1600&height=1600",
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"edit",
"permissions",
"version_history"]
}]
},
"path": "/",
"modified": 1460030191779
},
{
"action": "download",
"newVersion": {
"checksum": "e8d1be53d24895ae5cfc2808bec152bc",
"name": "test1.txt"
},
"totalLength": 36,
"created": 1460030191867,
"path": "/",
"modified": 1460030191867
},
{
"action": "download",
"newVersion": {
"checksum": "767c4efab82482dcfafdcdbc034800d4",
"name": "test2.txt"
},
"totalLength": 36,
"created": 1460030191931,
"path": "/",
"modified": 1460030191931
}]
}
}

== Download a file ==

Downloads a file from the server.

GET <code>/ajax/drive?action=download</code>

or

PUT <code>/ajax/drive?action=download</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to download.
* <code>checksum</code> - The checksum of the file version to download.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>offset</code> (optional) - The start offset in bytes for the download. If not defined, an offset of <code>0</code> is assumed.
* <code>length</code> (optional) - The number of bytes to include in the download stream. If not defined, the file is read until the end.

Request Body: 
Optionally, available since API version 3, if client-side file- and/or directory exclusion filters are active, a PUT request can be used. The request body then holds a JSON object containing two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[File_pattern|File patterns]] and [[Directory_pattern|Directory patterns]] accordingly. See [[Client_side_filtering|Client side filtering]] for details.

Response: 
The binary content of the requested file version. Note that in case of errors, an exception is not encoded in the default JSON error format here. Instead, an appropriate HTTP error with a status code != 200 is returned. For example, in case of the requested file being deleted or modified in the meantime, a response with HTTP status code 404 (not found) is sent.

Example:
==> GET http://192.168.32.191/ajax/drive?action=download&root=56&path=/test2&name=Jellyfish.jpg&checksum=5a44c7ba5bbe4ec867233d67e4806848&offset=0&length=-1&session=5d0c1e8eb0964a3095438b450ff6810f

<== HTTP 200 OK (20.0011 ms elapsed, 775702 bytes received)

== Upload a file ==

Uploads a file to the server.

PUT <code>/ajax/drive?action=upload</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>newName</code> - The target name of the file version to upload.
* <code>newChecksum</code> - The target checksum of the file version to upload.
* <code>name</code> (optional) - The previous name of the file version being uploaded. Only set when uploading an updated version of an existing file to the server.
* <code>checksum</code> - The previous checksum of the file version to upload. Only set when uploading an updated version of an existing file to the server.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>contentType</code> (optional) - The content type of the file. If not defined, <code>application/octet-stream</code> is assumed.
* <code>offset</code> (optional) - The start offset in bytes for the upload when resuming a previous partial upload. If not defined, an offset of <code>0</code> is assumed.
* <code>totalLength</code> (optional) - The total expected length of the file (required to support resume of uploads). If not defined, the upload is assumed completed after the operation.
* <code>created</code> (optional) - The creation time of the file as timestamp.
* <code>modified</code> (optional) - The last modification time of the file as timestamp. Defaults to the current server time if no value or a value larger than the current time is supplied.
* <code>binary</code> - Expected to be set to <code>true</code> to indicate the binary content.
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request body: 
The binary content of the uploaded file version.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=upload&root=56&path=/test2&newName=Penguins.jpg&newChecksum=9d377b10ce778c4938b3c7e2c63a229a&contentType=image/jpeg&offset=0&totalLength=777835&binary=true&device=Laptop&created=1375343426999&modified=1375343427001&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
[application/octet-stream;, 777835 bytes]

<== HTTP 200 OK (108.0062 ms elapsed, 118 bytes received)
< Content:
{
"data" : [{
"action" : "acknowledge",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
}
]
}

== Listen for changes (long polling) ==

Listens for server-side changes. The request blocks until new actions for the client are available, or an internal request timeout elapses. May return immediately if previously received but not yet processed actions are available for this client.

GET <code>/ajax/drive?action=listen</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.

Example:
==> GET http://192.168.32.191/ajax/drive?action=listen&root=65841&session=51378e29f82042b4afe4af1c034c6d68

<== HTTP 200 OK (63409.6268 ms elapsed, 28 bytes received)
< Content:
{
"data" : [{
"action" : "sync"
}
]
}

Alterantively, since API version 5, it's also possible to poll for changes in more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=listen</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to listen for changes in.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. The relevant root folder identifier is available in the <code>root</code> parameter of the action. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=listen&session=51378e29f82042b4afe4af1c034c6d68
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"root" : "129137"
}
]
}

== Get quota ==

Gets the quota limits and current usage for the storage the supplied root folder belongs to. Depending on the filestore configuration, this may include both restrictions on the number of allowed files and the total size of all contained files in bytes. If there's no limit, -1 is returned.

GET <code>/ajax/drive?action=quota</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Response: 
A JSON object containing the quota restrictions inside a JSON array with the property name <code>quota</code>. The JSON array contains zero, one or two <code>quota</code> objects as described below, depending on the filestore configuration. If one or more quota <code>type</code>s are missing in the array, the client can expect that there are no limitations for that type. Besides the array, the JSON object also contains a hyperlink behind the <code>manageLink</code> parameter, pointing to an URL where the user could manage his quota restrictions.

{| id="Quota" cellspacing="0" border="1"
|+ align="bottom" | Quota
! Name !! Type !! Value
|-
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).
|-
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).
|-
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).
|}

Example:
==> GET http://192.168.32.191/ajax/drive?action=quota&root=56&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (9.6854 ms elapsed, 113 bytes received)
< Content:
{
"data" : {
"quota" : [{
"limit" : 107374182400,
"use" : 1109974882,
"type" : "storage"
}, {
"limit" : 800000000000,
"use" : 1577,
"type" : "file"
}
],
"manageLink" : "https://www.example.com/manageQuota"
}
}

== Get Settings ==

Gets various settings applicable for the drive clients.

GET <code>/ajax/drive?action=settings</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>language</code> (optional) - The locale to use for language-sensitive settings (in the format <code><2-letter-language>_<2-letter-region></code>, e.g. <code>de_CH</code> or <code>en_GB</code>). Defaults to the user's configured locale on the server.

Response: 
A JSON object holding the settings as described below. This also includes a JSON array with the property name <code>quota</code> that contains zero, one or two quota objects as described below, depending on the filestore configuration. If one or more quota types are missing in the array, the client can expect that there are no limitations for that type.

{| id="Quota" cellspacing="0" border="1"
|+ align="bottom" | Quota
! Name !! Type !! Value
|-
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).
|-
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).
|-
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).
|}

{| id="Settings" cellspacing="0" border="1"
|+ align="bottom" | Settings
! Name !! Type !! Value
|-
| helpLink || String || A hyperlink to the online help.
|-
| quotaManageLink || String || A hyperlink to an URL where the user could manage his quota restrictions.
|-
| quota || Array || A JSON array containing the quota restrictions as described above.
|-
| serverVersion || String || The server version string.
|-
| supportedApiVersion || String || The API version supported by the server.
|-
| minApiVersion || String || The API version required to synchronize with the server.
|-
| localizedFolderNames || Object || A JSON object mapping the (relative) paths of directories to their localized name (based on the supplied <code>language</code> or the user's locale). Available with v7.8.1.
|-
| capabilities || Array || A JSON array holding relevant capabilities of the user. Available with v7.8.1.
|}

Example:
==> GET http://192.168.32.191/ajax/drive?action=settings&root=56&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (11.3530 ms elapsed, 318 bytes received)
< Content:
{
"data" : {
"quota" : [{
"limit" : 107374182400,
"use" : 8828427,
"type" : "storage"
}, {
"limit" : 800000000000,
"use" : 1559,
"type" : "file"
}
],
"helpLink" : "http://192.168.32.191/appsuite/help-drive/l10n/de_DE/index.html",
"quotaManageLink" : "http://192.168.32.191/manageQuota",
"serverVersion" : "7.8.1-Rev1",
"supportedApiVersion" : "4",
"minApiVersion" : "1",
"localizedFolderNames": {
"/Documents": "Dokumente",
"/Music": "Musik",
"/Pictures": "Bilder",
"/": "Meine Dateien",
"/Documents/Templates": "Vorlagen"
},
"capabilities" : [
"invite_guests",
"share_links",
"invite_users_and_groups"
]
}
}

== Subscribe to Push-Events ==

Registers a client device to receive push notifications from the server. The subscription is performed based on the configured root folder ID of the client application that identifies itself with it's device token. Supported services currently include the Apple Push Notification Service (APN) and Google Cloud Messaging (GCM). Trying to perform an identical subscription (same <code>root</code>, <code>service</code> and <code>token</code>) from the same user account again is treated as a no-op.

GET <code>/ajax/drive?action=subscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=subscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (13.6268 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

Alterantively, since API version 5, a subscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=subscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to subscribe to.

Response: 
An empty JSON result.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=subscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Unsubscribe from Push-Events ==

Unregisters a previously registered client device to stop receiving push notifications from the server. The same parameters that were used to perform the subscription need to be passed again, which includes the root folder ID, the device token and the service name.

GET <code>/ajax/drive?action=unsubscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=unsubscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (26.0015 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

Alterantively, since API version 5, an unsubscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=unsubscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to unsubscribe from.

Response: 
An empty JSON result.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=unsubscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Update the subscription token ==

Updates a device's registration token in case a new one was assigned by the service.

GET <code>/ajax/drive?action=updateToken</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The previous registration token as assigned by the service.
* <code>newToken</code> - The new registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=updateToken&service=apn&session=51378e29f82042b4afe4af1c034c6d68&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677&newToken=38919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (15.6653 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

== Get file metadata ==

Deprecated, available until API version 2. 
Additional metadata of synchronized files is made available via the <code>fileMetadata</code> request.

PUT <code>/ajax/drive?action=fileMetata</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>columns</code> - A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for file metadata are defined in [[#FileMetadata|File Metadata]].

Request Body: 
A JSON array containing the file versions to get the metadata for. Each object in the array should be sent as [[#File_Version | File Versions]], and needs to be present in the referenced path.

Response: 
A JSON array containing the file metadata in the order of the requested file versions. Each array element describes one file metadata and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

{| id="FileMetadataDeprecated" cellspacing="0" border="1"
|+ align="bottom" | File Metadata (deprecated)
! ID !! Name !! Type !! Value
|-
| name || String || The name of the file version.
|-
| 4 || created || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| 5 || modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| 702 || name || String || The name of the file, including it's extension, e.g. <code>test.doc</code>.
|-
| 703 || contentType || String || The file's content type, e.g. "image/png".
|-
| 708 || checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|-
| 750 || previewLink || String || A direct link to a medium-sized preview image of the file if available.
|-
| 751 || directLinkFragments || String | The fragments part of the direct link that can be used in combination with the [[http://oxpedia.org/index.php?title=HTTP_API#Token_Login_.28since_7.0.1.29 |token login]] method to jump directly to the detail view of the file in the web interface, bypassing the need to login manually.
|-
| 752 || directLink || String || A direct link to the detail view of the file in the web interface.
|-
| 753 || thumbnailLink || String || A direct link to a small thumbnail image of the file if available.
|}

Example:
==> PUT http://192.168.32.191/ajax/drive?action=fileMetadata&root=97974&path=%2f&columns=702%2c708%2c752%2c750%2c753&session=43aca91a80de42559ff0c2493dd973d0
> Content:
[
{
"name" : "image.jpg",
"checksum" : "2b04df3ecc1d94afddff082d139c6f15"
}, {
"name" : "song.mp3",
"checksum" : "5a9a91184e611dae3fed162b8787ce5f"
}, {
"name" : "test1.txt",
"checksum" : "7e36f409a042f06ecb88606a97a88c8f"
}, {
"name" : "test3.txt",
"checksum" : "703bc9aabff33faf07cf121dcda12ec8"
}
]

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
[
["image.jpg", "2b04df3ecc1d94afddff082d139c6f15", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179629", "https://192.168.32.191/ajax/files?action=document&folder=97974&id=179629&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179629"],
["song.mp3", "5a9a91184e611dae3fed162b8787ce5f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179630", "https://192.168.32.191/ajax/image/file/mp3Cover?folder=97974&id=179630&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179630"],
["test1.txt", "7e36f409a042f06ecb88606a97a88c8f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179626", null, "m=infostore&f=97974&i=179626"],
["test3.txt", "703bc9aabff33faf07cf121dcda12ec8", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179624", null, "m=infostore&f=97974&i=179624"]
]

== Get a direct link for a folder/a file into appsuite ==

Available since API version 4. 

Generate a direct link into appsuite UI for a synchronized file/a synchronized folder and a token for token-based login.

POST <code>/ajax/drive?action=jump</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file in the synchronized folder given in <code>path</code>-parameter. Optional
* <code>method</code> - [[#Methods | Methods]]
* <code>authId</code> - Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
* <code>clientToken</code> - Client side identifier for accessing the session later. The value should be some token that is unique for every login request.

Methods: 
* <code>edit</code>: Open the file in appsuite editor or in text/spreadsheet (if available).
* <code>permissions</code>: Open the file's/folder's change-permission dialog.
* <code>version_history</code>: Open the file's version history summary.
* <code>preview</code>: Open the file's/folder's preview.

Response: 
A JSON array containing the direct link to the file/folder including a server token for token based login.

Example:
==> POST http://localhost/ajax/drive?action=jump&session=48a289898ad949faaa46c04e7fb422f5&root=9547&path=/path/to/file&name=file_to_edit.txt&method=edit&authId=41763584-8460-11e4-b116-123b93f75dba
> Content: clientToken=47d74b1c-81df-11e4-b116-123b93f75cba

<== HTTP 200 OK
< Content:
{
"data": {
"redirectUrl": "http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68"
}
}

== Use direct link and token with token-based login ==

Available since API version 4. 

Login to appsuite UI with token-based login via the link created with [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].

GET <code>[direct link]</code>

Parameters:
* <code>clientToken</code> – Client side identifier for accessing the session. The value must be the same as in [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].

Example:
==> GET http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68&clientToken=47d74b1c-81df-11e4-b116-123b93f75cba

<== HTTP 200 OK

== Get synchronizable Folders ==

Available since API version 4. 

Allows getting a list of folders that are available on the server for synchronization. This request should be used to build up a folder tree and let the user select the root synchronization folder(s).

GET <code>/ajax/drive?action=subfolders</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>parent</code> - The ID of the parent folder to get the subfolders for as read from a previously fetched directory metadata object. Optional; if not set, the root available root folders are returned.

Response: 
A JSON array holding metadata information for all subfolders as defined in [[#DirectoryMetadata | Directory Metadata]], with the <code>files</code> array being left out.

Example:
==> GET http://192.168.32.191/ajax/drive?action=subfolders&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (241.0252 ms elapsed, 966 bytes received)
< Content:
{
"data": [{
"id": "com.openexchange.file.storage.googledrive://1/",
"name": "Google Drive",
"path": "/Google Drive",
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
},
{
"id": "10",
"name": "Freigegebene Dateien",
"path": "/Freigegebene Dateien",
"created": 1224493261628,
"modified": 1417164170136,
"has_subfolders": true,
"own_rights": 1,
"permissions": [{
"bits": 1,
"group": true,
"entity": 0,
"display_name": "All users",
"guest": false
},
{
"bits": 1,
"group": true,
"entity": 2147483647,
"display_name": "Guests",
"guest": false
}],
"jump": ["permissions"],
"shared": true
},
{
"id": "15",
"name": "Öffentliche Dateien",
"path": "/Öffentliche Dateien",
"created": 1224493261628,
"modified": 1418383637250,
"has_subfolders": true,
"own_rights": 403709956,
"permissions": [{
"bits": 403709956,
"group": true,
"entity": 0,
"display_name": "All users",
"guest": false
},
{
"bits": 1,
"group": true,
"entity": 2147483647,
"display_name": "Guests",
"guest": false
}],
"jump": ["permissions"],
"shared": true
},
{
"id": "com.openexchange.file.storage.dropbox://1/",
"name": "Dropbox",
"path": "/Dropbox",
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
},
{
"id": "9542",
"name": "Meine Dateien",
"path": "/Meine Dateien",
"created": 1320230546147,
"modified": 1426764458823,
"default_folder": true,
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
}]
}

== Get a share link ==

Available since API version 4. 

Creates a new or gets the previously created link for a file or folder that can be used to access the item in a browser by anyone. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=getLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to get the link for as described in [[#DriveShareTarget|Drive Share Target]].

Response: 
A JSON object containing details about the share link, including its URL, as described in [[HTTP_API#ShareLink|Share Link]]. Additionally, the current checksum of the share target is included (starting with v7.8.1).

{| id="DriveShareTarget" cellspacing="0" border="1"
|+ align="bottom" | Drive Share Target
! Name !! Type !! Value
|-
| name || String || (Optional) The name of the file, including its extension, e.g. <code>test.doc</code>. Not set if the target is a directory.
|-
| path || String || The path of the (file's parent) directory, relative to the root folder.
|-
| checksum || String || The MD5 hash of the file or directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

Example 1: Get the intial link for a file
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (311.8978 ms elapsed, 118 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": true,
"checksum": "bdf3bf1da3405725be763540d6601144"
}
}

Example 2: Get an already existing link for a file
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (78.0547 ms elapsed, 167 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": false,
"expiry_date": 1451606400000,
"password": "secret",
"checksum": "bdf3bf1da3405725be763540d6601144"
}
}

== Update a share link ==

Available since API version 4. 

Updates a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request Body: 
A JSON object as described in [[HTTP_API#ShareLink|Share Link]] containing the properties of the link to update, as well as the share target itself as described in [[#DriveShareTarget|Drive Share Target]]. Only modified fields should be set.

Response: 
A JSON object containing details about the share link, including its URL, as described in [[HTTP_API#ShareLink|Share Link]]. Additionally, the current checksum of the share target is included (starting with v7.8.1).

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144",
"password": "secret",
"expiry_date": 1451606400000
}

<== HTTP 200 OK (341.8978 ms elapsed, 218 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": false,
"checksum": "bdf3bf1da3405725be763540d6601144",
"password": "secret",
"expiry_date": 1451606400000
}
}

== Delete a share link ==

Available since API version 4. 

Deletes a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=deleteLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to delete the link for as described in [[#DriveShareTarget|Drive Share Target]].

Response: 
An empty JSON object.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=deleteLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (149.3251 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Send a share link ==

Available since API version 4. 

Sends a notification message for a share link to one or more recipients.

PUT <code>/ajax/drive?action=sendLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to send the link for as described in [[#DriveShareTarget|Drive Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by <code>null</code> values. Optionally, a custom notification message may be specified in a <code>message</code> property (otherwise, some default message is used).

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=sendLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144",
"recipients": [
["Otto Example", "otto@example.com"],
["Horst Example", "horst@example.org"]
]
}

<== HTTP 200 OK (260.9242 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Get shares ==

Available since API version 4. 

Gets all files and directories within the synchronized tree that are shared to others.

GET <code>/ajax/drive?action=shares</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Response: 
The metadata of the shared items as a JSON object holding two JSON arrays <code>files</code> and <code>directories</code> containing the metadata as defined in [[#FileMetadata|File Metadata]] and [[#Directory_Metadata|DirectoryMetadata]] respectively.

Example:
==> GET http://192.168.32.191/ajax/drive?action=shares&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542

<== HTTP 200 OK (191.2707 ms elapsed, 5339 bytes received)
< Content:
{
"data": {
"directories": [{
"id": "316770",
"name": "test",
"checksum": "bef03e92c3c675c1a6efddc831ac21b9",
"localized_name": "test",
"path": "/test",
"created": 1437989289761,
"modified": 1438176370780,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
{
"bits": 135274497,
"entity": 8340,
"display_name": "Otto Example",
"email_address": "otto@example.com",
"type": "guest"
},
{
"bits": 257,
"entity": 16175,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_permissions": [{
"entity": 182,
"bits": 403710016,
"type": "user",
"display_name": "Mander, Jens",
"contact": {
"email1": "jens.mander@example.com",
"last_name": "Mander",
"first_name": "Jens"
}
},
{
"entity": 8340,
"bits": 135274497,
"type": "guest",
"display_name": "Otto Example",
"contact": {
"email1": "otto@example.com"
}
},
{
"entity": 16175,
"bits": 257,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/102b560404b3e96c9623be94b3d643829a46b117558d9ec9/31342f1f"
}],
"jump": ["permissions"],
"shared": true,
"shareable": true
},
{
"id": "300695",
"name": "sharetest",
"checksum": "cdfb5724f9614290a850ec507aea72a2",
"localized_name": "sharetest",
"path": "/sub1/check/sharetest",
"created": 1430218822598,
"modified": 1430218833769,
"own_rights": 403710016,
"permissions": [{
"bits": 257,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"type": "user"
},
{
"bits": 403710016,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
}],
"extended_permissions": [{
"entity": 10,
"bits": 257,
"type": "user",
"display_name": "Klaus Mander",
"contact": {
"email1": "klaus.mander@example.com",
"title": "",
"last_name": "Mander",
"first_name": "Klaus",
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"
}
},
{
"entity": 182,
"bits": 403710016,
"type": "user",
"display_name": "Mander, Jens",
"contact": {
"email1": "jens.mander@example.com",
"last_name": "Mander",
"first_name": "Jens"
}
}],
"jump": ["permissions"],
"shared": true,
"shareable": true
}],
"files": [{
"name": "Chrysanthemum.jpg",
"created": 1438177192835,
"modified": 1438177729597,
"created_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"modified_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"preview": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",
"thumbnail": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",
"object_permissions": [{
"bits": 1,
"entity": 16178,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_object_permissions": [{
"entity": 16178,
"bits": 1,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/1224dd0b065f2076b6db0e665f1f441f89f1308ad2a8ad7f/167e4881"
}],
"shared": true,
"shareable": true,
"jump": ["preview",
"permissions"],
"path": "/Pictures",
"checksum": "076e3caed758a1c18c91a0e9cae3368f"
},
{
"name": "data.zip",
"created": 1427291138800,
"modified": 1438593586254,
"created_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"modified_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"object_permissions": [{
"bits": 4,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"type": "user"
},
{
"bits": 4,
"entity": 8338,
"display_name": "Horst Example",
"email_address": "horst@example.com",
"type": "guest"
},
{
"bits": 1,
"entity": 11224,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_object_permissions": [{
"entity": 10,
"bits": 4,
"type": "user",
"display_name": "Klaus Mander",
"contact": {
"email1": "klaus.mander@example.com",
"title": "",
"last_name": "Mander",
"first_name": "Klaus",
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"
}
},
{
"entity": 8338,
"bits": 4,
"type": "guest",
"display_name": "Horst Example",
"contact": {
"email1": "horst@example.com"
}
},
{
"entity": 11224,
"bits": 1,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/1f74962e0b55529663dfbc3b55794ea59b753c9301c0da75/76c846ae"
}],
"shared": true,
"shareable": true,
"jump": ["permissions"],
"path": "/Projects/ACME",
"checksum": "d63540e8f986ec305b0dd1293d8a3276"
}]
}
}

== Get directory metadata ==

Available since API version 4. 

Gets metadata of a specific synchronized directory.

GET <code>/ajax/drive?action=getFolder</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the directory to update, relative to the root folder.
* <code>checksum</code> - The checksum of the directory to update.

Response: 
A JSON object representing the requested directoy metadata as described in [[#DirectoryMetadata|Directory Metadata]].

== Get file metadata ==

Available since API version 4. 

Gets metadata of a specific synchronized file.

PUT <code>/ajax/drive?action=getFile</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to update.
* <code>checksum</code> - The checksum of the file version to update.

Response: 
A JSON object representing the requested directory metadata as described in [[#FileMetadata|File Metadata]].

== Update directory metadata ==

Available since API version 4. 

Updates specific metadata of a synchronized directory. This currently only includes the permissions - which in turn is only allowed for folders marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateFolder</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the directory to update, relative to the root folder.
* <code>checksum</code> - The checksum of the directory to update.

Request body: 
A JSON object named <code>folder</code> describing the updated folder metadata as described in [[HTTP_API#DetailedFolderData|Detailed Folder Data]]. Currently, only the property <code>permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e
> Content:
{
"folder": {
"permissions": [{
"group": false,
"bits": 403710016,
"entity": 182
},
{
"type": "guest",
"email_address": "otto@example.com",
"display_name": "Otto Example",
"bits": 135274497
}]
},
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (207.1722 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Update file metadata ==

Available since API version 4. 

Updates specific metadata of a synchronized file. This currently only includes the object permissions - which in turn is only allowed for files marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateFile</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to update.
* <code>checksum</code> - The checksum of the file version to update.

Request body: 
A JSON object named <code>file</code> describing the updated file metadata as described in [[HTTP_API#DetailedInfoitemData|Detailed Infoitem Data]]. Currently, only the property <code>object_permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e
> Content:
{
"file": {
"object_permissions": [{
"type": "guest",
"email_address": "otto@example.com",
"display_name": "Otto Example",
"bits": 16641
}]
},
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Notify about shared items ==

Available since API version 4. 

(Re-)Sends a share notification to one or more permission entities of a specific shared file or folder.

PUT <code>/ajax/drive?action=notify</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to send the notification for as described in [[#DriveShareTarget|Drive Share Target]]. The entity IDs of the recipients are listed in the JSON array named <code>entities</code>. Optionally, an additional JSON object <code>notification</code> may be included, inside of which a custom <code>message</code> can be passed (otherwise, some default message is used).

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=notify&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/test",
"name": "image.jpg",
"checksum": "d63540e8f986ec305b0dd1293d8a3276",
"entities": [10,78],
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (45.2084 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

= File- and Directory Name Restrictions =

Regarding the case sensitivity of file and directory names, OX Drive works in a case-insensitive, but case-preserving way. That means that there cannot be two files with an equal name ignoring case in the same directory, but it's still possible to synchronize the names in a case-sensitive manner, as well as it's possible to change only the case of file- and directory names.

The same applies to equally named files and directories on the same level in the folder hierarchy, i.e. it's not possible to create a new file in a directory where an equally (ignoring case) named subdirectory already exists and vice versa.

There is a similar restriction regarding file and directory names in the same directory having different unicode normalization forms, yet the same textual representation. OX Drive requires uniqueness regarding this textual representaion of potentially different encoded unicode strings. So, in case the client tries to synchronize two textually equal files or directories, he is instructed to put one of them into quarantine. Internally the server performs an equals-check of the "NFC" normalization forms of the strings, i.e. an unicode string is normalized using full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. Details regarding unicode normalization can be found at http://www.unicode.org/reports/tr15/tr15-23.html .

== Invalid and ignored Filenames ==

There are some filenames that are invalid or ignored and therefore not synchronized. This means that files with these names should not be taken into account when sending the directory contents to the server, or when calculating the directory checksum (see below). The following list describes when a filename is considered invalid:
* If it contains one or of the following reserved characters:
** <code><</code> (less than),
** <code>></code> (greater than)
** <code>:</code> (colon)
** <code>"</code> (double quote)
** <code>/</code> (forward slash)
** <code>\</code> (backslash)
** <code>|</code> (vertical bar or pipe)
** <code>?</code> (question mark)
** <code>*</code> (asterisk)
** Characters whose integer representations are in the range from 0 through 31
* The last character is a <code>.</code> (dot) or <code>' '</code> (space)
* It's case-invariant name without an optional extension matches one of the reserved names <code>CON</code>, <code>PRN</code>, <code>AUX</code>, <code>NUL</code>, <code>COM1</code>, <code>COM2</code>, <code>COM3</code>, <code>COM4</code>, <code>COM5</code>, <code>COM6</code>, <code>COM7</code>, <code>COM8</code>, <code>COM9</code>, <code>LPT1</code>, <code>LPT2</code>, <code>LPT3</code>, <code>LPT4</code>, <code>LPT5</code>, <code>LPT6</code>, <code>LPT7</code>, <code>LPT8</code>, or <code>LPT9</code>
* It consists solely of whitespace characters

The following list gives an overview about the ignored filenames:
* <code>desktop.ini</code>
* <code>Thumbs.db</code>
* <code>.DS_Store</code>
* <code>icon\r</code>
* Any filename ending with <code>.drivepart</code>
* Any filename starting with <code>.msngr_hstr_data_</code> and ending with <code>.log</code>

Nevertheless, if the client still insists to send a file version with an invalid or ignored filename, the file creation on the server is refused with a corresponding <code>error</code> action (see below).

== Invalid and ignored Directory Names ==

There are also similar restrictions regarding invalid directory names. Any try to include them in the list of directory versions will be responded with a corresponding error action for the directory version. The following list describes when a path is considered invalid:
* If it contains one or of the following reserved characters:
** <code><</code> (less than),
** <code>></code> (greater than)
** <code>:</code> (colon)
** <code>"</code> (double quote)
** <code>\</code> (backslash)
** <code>|</code> (vertical bar or pipe)
** <code>?</code> (question mark)
** <code>*</code> (asterisk)
** Characters whose integer representations are in the range from 0 through 31
* The last character of any subpath (i.e. the last part of the whole path or the part preceding the spearator character <code>/</code>) is a <code>.</code> (dot) or <code>' '</code> (space)
* It consists solely of whitespace characters
* It not equals the root path <code>/</code>, but ends with a <code>/</code> (forward slash) character
* It contains two or more consecutive <code>/</code> (forward slash) characters

The following list gives an overview about the ignored directory names:
* <code>/.drive</code>
* Any directory whose path ends with <code>/.msngr_hstr_data</code>

== Length Restrictions ==

The maximum allowed length for path segments, i.e. the parts between forawrd slashes (</code>/</code>) in directory and filenames, is restricted to 255 characters. Synchronizing a file or directory version that contains path segments longer than this limit leads to those versions being put into quarantine.

= Client side filtering =

Client-side filtering is available since API version 2. 

OX Drive clients may define a user- and/or application-defined list of file- and directory name exclusions. Those exclusion filters are then taken into account during synchronization, i.e. files and directories matching a defined exclusion pattern are ignored when comparing the list of server-, client- and original versions. Also, the file exclusion lists are considered for the calculation of aggergated directory checksums.

The exclusion filters may be set, changed or unset at any time during synchronization, there are no additional requests needed to set them up. Instead, the list of excluded files and directories is simply sent along with each <code>syncFolders</code>, <code>syncFiles</code> and <code>download</code> request. The following tables show the JSON representation of file- and directory patterns that are used to build up the exlcusion lists:

== Directory pattern ==

A directory pattern is defined by a pattern string and further attributes.

{| id="DirectoryPattern" cellspacing="0" border="1"
|+ align="bottom" | Directory Pattern
! Name !! Type !! Value
|-
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>.
|-
| path || String || The path pattern, in a format depending on the pattern type.
|-
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code>
|}

== File pattern ==

A file pattern is defined by pattern strings for the filename and path, as well as further attributes.

{| id="FilePattern" cellspacing="0" border="1"
|+ align="bottom" | File Pattern
! Name !! Type !! Value
|-
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>.
|-
| path || String || The path pattern, in a format depending on the pattern type.
|-
| name || String || The filename pattern, in a format depending on the pattern type.
|-
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code>
|}

== Pattern types ==

A pattern currently may be defined in two formats: <code>exact</code> or <code>glob</code>.

* <code>exact</code> An exact pattern, matching the file- or directory version literally. For example, to exclude the file <code>Backup.pst</code> in the subfolder <code>Mail</code> below the root synchronization folder, an <code>exact</code> file pattern would look like: <code>{"path":"/Mail","name":"Backup.pst","type":"exact"}</code>, or, an <code>exact</code> directory pattern for the directory <code>/Archive</code> would be represented as <code>{"path":"/Archive","type":"exact"}</code>.
* <code>glob</code> A simple pattern allowing to use the common wildcards <code>*</code> and <code>?</code> to match file- and directory versions. For example, to exclude all files ending with <code>.tmp</code> across all directories, the <code>glob</code> file pattern could be defined as <code>{"path":"*","name":"*.tmp","type":"glob"}</code>, or, to exclude the directory <code>/Project/.git</code> and all its subdirectories recursively, this would be expressed using a combination of the following two directory patterns: <code>[{"path":"/Project/.git","type":"exact"},{"path":"/Project/.git*","type":"glob"}]</code>.

== Further considerations ==

* It's possible to exclude a (parent) directory with an appropriate pattern, while still subfolders below that directory being synchronized. This usually results in the excluded directory being created ob both client- and server side, but no file contents within the excluded directory being exchanged. If subfolders should be excluded, too, a wildcard should be used in the pattern to match any subdirectories.
* If the client tries to synchronize a file- or directory version that is ignored, i.e. a version that would match any of the provided exclusion filters, the server behaves similarly to the handling of invalid and ignored file- and directory names (see above), i.e. the client would be instructed to put those versions into quarantine.
* For the calculation of directory checksums, it's important that the server and client perform exactly the same matching for ignored filenames: A <code>*</code> character matches zero or more characters, a <code>?</code> character matches exactly one character. All other characters are matched literally. Advanced glob flavors like braces to define subpattern alternatives or square brackets for character sets are not used.
* Client-side filtering is available with API version 2. The API version that is supported by the server is included in the response of the [[#Get Settings | Settings]] request.
* Whenever there are active exclusion filters, the <code>syncFolders</code> request should contain all of both directory and file exclusion filter lists. For the <code>syncFiles</code> request, it's sufficient to include the list of file exclusions.

= Metadata Synchronization =

The synchronization of metadata is available since API version 3. 

== Introduction ==

Previously, only the "raw" folders and files were synchronized between server and clients. While this is sufficient for basic synchronization, there are cases where the clients could benefit from additional data - "metadata" - that is already available on the server. For example, clients could display directories that have been shared or published to other people in a different way. Or, clients could consider folder permissions directly in case the user is performing a local change that would be rejected by the server in the next synchronization cycle anyway.

To supply the clients with those additional information without any influence on the existing synchronization protocol (!), <code>.drive-meta</code> files are introduced for each synchronized directory. Regarding synchronization, such files are treated like any other ordinary file. Especially, those files are taken into account when it comes to directory checksum calculation. Doing so, metadata updates result in a changed <code>.drive-meta</code> file, which in turn causes the parent directory checksum to change, hence synchronization is triggered.

However, some special handling applies for those files:

* Clients are not allowed to change metadata, so modifications of metadata files or the deletion of them is rejected. Recovery is done via the protocol here, i.e. the client is instructed to re-download the file.
* <code>.drive-meta</code> files are actually not stored physically on the file storage backend, but created on the fly based on the actual metadata of the directory.
* Client applications may either store such files on the client file system, or evaluate and store the contained metadata information in a local database for later retrieval. If the file is not saved physically on the client (which is actually recommended), the client is responsible to consider the metadata file in a virtual way and include it's checksum for the directory checksum calculation - similar to the server's internal handling.

Note: Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.

== Metadata format ==

The metadata in <code>.drive-meta</code> files is serialized in JSON format to allow easy processing at the clients. The following shows an example of the contents:
{
"path": "/",
"localized_name": "Meine Dateien",
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"shareable": true,
"jump": ["permissions"],
"files": [{
"name": "Koala.jpg",
"created": 1418024190565,
"modified": 1418026995663,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",
"thumbnail": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",
"object_permissions": [{
"bits": 1,
"group": false,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"guest": false
},
{
"bits": 1,
"group": false,
"entity": 8338,
"email_address": "horst@example.com",
"guest": true
}],
"shareable": true,
"shared": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"permissions",
"version_history"]
},
{
"name": "test.txt",
"created": 1418024198520,
"modified": 1418027394897,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=800&height=800",
"thumbnail": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=100&height=100",
"locked": true,
"shareable": true,
"number_of_versions": 4,
"version": "6",
"version_comment": "Uploaded with OX Drive (TestDrive)",
"versions": [{
"name": "test.txt",
"file_size": 23,
"created": 1418024198520,
"modified": 1418024202878,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "1",
"version_comment": "Uploaded with OX Drive (TestDrive)"
},
{
"name": "test.txt",
"file_size": 54,
"created": 1418024234782,
"modified": 1418024231522,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "2",
"version_comment": "Uploaded with OX Drive (TestDrive)"
},
{
"name": "test.txt",
"file_size": 120,
"created": 1418027349026,
"modified": 1418027355957,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "5"
},
{
"name": "test.txt",
"file_size": 127,
"created": 1418027370051,
"modified": 1418027366945,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "6",
"version_comment": "Uploaded with OX Drive (TestDrive)"
}],
"jump": ["preview",
"edit",
"permissions",
"version_history"]
},
{
"name": "Kalimba.mp3",
"created": 1418026529047,
"modified": 1247549551659,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=800&height=800",
"thumbnail": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"version_comment": "Uploaded with OX Drive (TestDrive)",
"jump": ["preview",
"permissions",
"version_history"]
}]
}

The following objects describe the JSON structure of the metadata for a directory:

{| id="DirectoryMetadata" cellspacing="0" border="1"
|+ align="bottom" | Directory Metadata
! Name !! Type !! Value
|-
| id || String || The server-side unique identifier of the directory.
|-
| localized_name || String || The localized display name of the directory, if different from the physical name.
|-
| checksum || String || The directory's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| own_rights || Number|| Folder permissions which apply to the current user, as described in [[HTTP_API#PermissionFlags | Permission Flags]].
|-
| permissions || Array || All folder permissions, each element is an object as described in [[HTTP_API#PermissionObject | Permission Object]].
|-
| extended_permissions || Array || All folder permissions including some additional information, each element is an object as described in [[HTTP_API#ExtendedPermissionObject | Extended Permission Object]].
|-
| default_folder || Boolean || <code>true</code> if the folder is a default folder, <code>false</code> or not set, otherwise.
|-
| has_subfolders || Boolean || <code>true</code> if the folder (potentially) has subfolders, <code>false</code> or not set, otherwise.
|-
| shared || Boolean || <code>true</code> if the folder is shared, <code>false</code> or not set, otherwise.
|-
| shareable || Boolean || <code>true</code> if the folder can be shared to others by the user, <code>false</code> or not set, otherwise.
|-
| not_synchronizable || Boolean || <code>true</code> if the folder is exluded from synchronization, <code>false</code> or not set, otherwise.
|-
| type || Number || The special folder type, or not set, if not available.
|-
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the folder.
|-
| files || Array || Metadata for the contained files, each element is an object as described in [[#FileMetadata | File Metadata]]. Only set if metadata is retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|}

{| id="FileMetadata" cellspacing="0" border="1"
|+ align="bottom" | File Metadata
! Name !! Type !! Value
|-
| name || String || The name of the file the metadata belongs to.
|-
| checksum || String || The file's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| path || String || The path of the parent directory. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| created || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| created_by || Number || User ID of the user who created this object.
|-
| modified_by || Number || User ID of the user who last modified this object.
|-
| content_type || String || The content type of the file.
|-
| preview || String || A URL to a preview image for the file.
|-
| thumbnail || String || A URL to a thumbnail image for the file.
|-
| object_permissions || Array || All file permissions, each element is an object as described in [[#HTTP_API#ObjectPermissionObject | Object Permission Object]].
|-
| extended_object_permissions || Array || All file permissions including some additional information, each element is an object as described in [[HTTP_API#ExtendedObjectPermissionObject | Extended Object Permission Object]].
|-
| shared || Boolean || <code>true</code> if the file is shared, <code>false</code> or not set, otherwise.
|-
| shareable || Boolean || <code>true</code> if the file can be shared to others by the user, <code>false</code> or not set, otherwise.
|-
| locked || Boolean || <code>true</code> if the file is locked, <code>false</code> or not set, otherwise.
|-
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the file.
|-
| number_of_versions || Number | The number of all versions of the file.
|-
| version || String || The current version identifier (usually, but not necessarily a numerical value) of the file.
|-
| version_comment || String | An additional comment for the file version.
|-
| versions || Array || Metadata for all versions of the file, each element is an object as described in [[#File_Version | File Version]].
|}

{| id="FileVersion" cellspacing="0" border="1"
|+ align="bottom" | File Version
! Name !! Type !! Value
|-
| name || String || The name of the file version.
|-
| file_size || Number || The file size of the version in bytes.
|-
| created || Timestamp || The file version's last modification time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file version's last modification time (always UTC, not translated into user time).
|-
| created_by || Number || User ID of the user who created this object.
|-
| modified_by || Number || User ID of the user who last modified this object.
|-
| version || String || The version identifier (usually, but not necessarily a numerical value) of the file version.
|-
| version_comment || String || An additional comment for the file version.
|}

== Client-side implementation ==

In order to make use of the metadata, clients should roughly implement the following:
* Include the <code>apiVersion</code> parameter in each request, and set it to at least <code>3</code> in order to include <code>.drive-meta</code> during synchronization
* Evaluate <code>.drive-meta</code> files and store the information, as well as the file's checksums in a local database
* Include this file in the calculation of the parent directory checksum, just like an ordinary file in that directory
* Do something useful with the metadata information.

== Additional notes ==

* The metadata synchronization via <code>.drive-meta</code> files embedded into the synchronization protocol obsoletes the previously used methods to receive metadata information ([[#Get_file_metadata]] and <code>columns</code> parameter in [[#Synchronize_files_in_a_folder]].
* Depending on the underlying file storage backend, the included metadata may vary, so each information should be treatened as optional.
* Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.

== Possible use cases ==
* For files where the <code>locked</code> property is <code>true</code>, display some kind of "lock" icon (-overlay) in the file list / explorer view
* For files or folders where the <code>shared</code> property is <code>true</code>, display some kind of "cloud" icon (-overlay) in the file list / explorer view
* For files or folders where the user is not allowed to perform an action with, don't offer such actions (e.g. if a file cannot be deleted or renamed by the user due to insufficient permissions, disable the corresponding options)
* Use the URLs in <code>preview</code> and <code>thumbnail</code> to get a preview image for the files
* Display the server creation / last modification timestamps of files and folders
* Embed a version history for files with multiple versions
* Show to which users a file or folder is currently shared
* Offer appropriate "jump" actions to the groupware web interface for more advanced options (e.g. to directly edit an .xlsx file in the spreadsheet application of the web interface, or to manage a folder's permission

OX Drive API

2016-05-30T13:16:43Z

Tobias.friedrich: /* Synchronize files in a folder */

<div class="title">OX Drive API</div>

__TOC__

= Introduction =

The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side.

The synchronization is based on checksums for files and folders, differences between the server- and client-side are determined using a three-way comparison of server, client and previously acknowledged file- and directory-versions. The synchronization logic is performed by the server, who instructs the client with a set of actions that should be executed in order to come to a synchronized state.

Therefore, the client takes a snapshot of it's local files and directories, calculates their checksums, and sends them as a list to the server, along with a list of previously acknowledged checksums. The server takes a similar snapshot of the files and directories on the underlying file storages and evaluates which further actions are necessary for synchronization. After executing the server-side actions, the client receives a list of actions that should be executed on the client-side. These steps are repeated until the server-state matches the client-state.

Key concept is that the synchronization works stateless, i.e. it can be interrupted and restarted at any time, following the eventual consistency model.

Entry point for the synchronization is the [[#Synchronize_folders|<code>syncfolders</code>]] request, where the directories are compared, and further actions are determined by the server, amongst others actions to synchronize the files in a specific directory using the [[#Synchronize_files_in_a_folder|<code>syncfiles</code>]] request. After executing the actions, the client should send another <code>syncfolders</code> request to the server and execute the returned actions (if present), or finish the synchronization if there are no more actions to execute. In pseudo-code, the synchronization routine could be implemented as follows:

WHILE TRUE
{
response = SYNCFOLDERS()
IF 0 == response.actions.length
BREAK
ELSE
EXECUTE(response.actions)
}

Basically, it's up to the client how often such a synchronization cycle is initiated. For example, he could start a new synchronization cycle after a fixed interval, if he recognizes that the client directories have changed, or if he is informed that something has changed on the server by an event. It's also up to the client to interrupt the synchronization cycle at any time during execution of the actions and continue later on, however, it's recommended to start a new synchronization cycle each time to avoid possibly outdated actions.

= API =

As part of the [[HTTP_API|HTTP API]], the basic conventions for exchanging messages described there are also valid for this case, especially the [[HTTP_API#Low_level_protocol|low level protocol]] and [[HTTP_API#Error_handling|error handling]]. Each request against the Drive API assumes a valid server session that is uniquely identified by the session id and the corresponding cookies and are sent with each request. A new session can be created via the [[HTTP_API#Module_.22login.22|login module]].

The root folder plays another important role for the message exchange. The root folder has a unique identifier. It is the parent server folder for the synchronization. All path details for directories and files are relative to this folder. This folder's id is sent with each request. To select the root folder during initial client configuration, the client may get a list of synchronizable folders with the [[#Get_synchronizable_Folders|<code>subfolders</code>]] action.

Subsequently all transferred objects and all possible actions are listed.

== File Version ==

A file in a directory is uniquely identified by its filename and the checksum of its content.

{| id="FileVersion" cellspacing="0" border="1"
|+ align="bottom" | File Version
! Name !! Type !! Value
|-
| name || String || The name of the file, including its extension, e.g. <code>test.doc</code>.
|-
| checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

== Directory Version ==

A directory is uniquely identified by its full path, relative to the root folder, and the checksum of its content.

{| id="DirectoryVersion" cellspacing="0" border="1"
|+ align="bottom" | Directory Version
! Name !! Type !! Value
|-
| path || String || The path of the directory, including the directory's name, relative to the root folder, e.g. <code>/sub/test/letters</code>.
|-
| checksum || String || The MD5 hash of the directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

Note: the checksum of a directory is calculated based on its contents in the following algorithm:

* Build a list containing each file in the directory (not including subfolders or files in subfolders)
* Ensure a lexicographically order in the following way:
** Normalize the filename using the <code>NFC</code> normalization form (canonical decomposition, followed by canonical composition) - see http://www.unicode.org/reports/tr15/tr15-23.html for details
** Encode the filename to an array of UTF-8 unsigned bytes (array of codepoints)
** Compare the filename (encoded as byte array "fn1") to another one "fn2" using the following comparator algorithm:

min_length = MIN(LENGTH(fn1), LENGTH(fn2))
FOR i = 0; i < min_length; i++
{
result = fn1[i] - fn2[i]
IF 0 != result RETURN result
}
RETURN LENGTH(fn1) - LENGTH(fn2)

* Calculate the aggregated MD5 checksum for the directory based on each file in the ordered list:
** Append the file's NFC-normalized (see above) name, encoded as UTF-8 bytes
** Append the file's MD5 checksum string, encoded as UTF-8 bytes

== Actions ==

All actions are encoded in the following format. Depending on the action type, not all properties may be present.

{| id="Actions" cellspacing="0" border="1"
|+ align="bottom" | Actions
! Name !! Type !! Value
|-
| action || String || The type of action to execute, currently one of <code>acknowledge</code>, <code>edit</code>, <code>download</code>, <code>upload</code>, <code>remove</code>, <code>sync</code>, <code>error</code>.
|-
| version || Object || The (original) file- or directory-version referenced by the action.
|-
| newVersion || Object || The (new) file- or directory-version referenced by the action.
|-
| path || String || The path to the synchronized folder, relative to the root folder.
|-
| root || String || The corresponding root folder identifier (optional, available since API version 5).
|-
| offset || Number || The requested start offset in bytes for file uploads.
|-
| totalLength || Number || The total length in bytes for file downloads.
|-
| contentType || String || The file's content type for downloads (deprecated, available until API version 2).
|-
| created || Timestamp || The file's creation time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| error || Object || The error object in case of synchronization errors.
|-
| quarantine || Boolean || The flag to indicate whether versions need to be excluded from synchronization.
|-
| reset || Boolean || The flag to indicate whether locally stored checksums should be invalidated.
|-
| stop || Boolean || The flag to signal that the client should stop the current synchronizsation cycle.
|-
| acknowledge || Boolean || The flag to signal if the client should not update it's stored checksums when performing an <code>EDIT</code> action.
|-
| thumbnailLink || String || A direct link to a small thumbnail image of the file if available (deprecated, available until API version 2).
|-
| previewLink || String || A direct link to a medium-sized preview image of the file if available (deprecated, available until API version 2).
|-
| directLink || String || A direct link to the detail view of the file in the web interface (deprecated, available until API version 2).
|-
| directLinkFragments || String || The fragments part of the direct link (deprecated, available until API version 2).
|}

The following list gives an overview about the used action types:

=== <code>acknowledge</code> ===
Acknowledges the successful synchronization of a file- or directory version, i.e., the client should treat the version as synchronized by updating the corresponding entry in its metadata store and including this updated information in all following <code>originalVersions</code> arrays of the <code>syncfiles</code> / <code>syncfolders</code> actions. Depending on the <code>version</code> and <code>newVersion</code> parameters of the action, the following acknowledge operations should be executed (exemplarily for directory versions, file versions are acknowledged in the same way):

* Example 1: Acknowledge a first time synchronized directory The server sends an <code>acknowledge</code> action where the newly synchronized directory version is encoded in the <code>newVersion</code> parameter. The client should store the version in his local checksum store and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.
{
"action" : "acknowledge",
"newVersion" : {
"path" : "/",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

* Example 2: Acknowledge a synchronized directory after updates The server sends an <code>acknowledge</code> action where the previous directory version is encoded in the <code>version</code>, and the newly synchronized directory in the <code>newVersion</code> parameter. The client should replace any previously stored entries of the directory version in his local checksum store with the updated version, and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.
{
"action" : "acknowledge",
"newVersion" : {
"path" : "/",
"checksum" : "7bb1f1a550e9b9ab4be8a12246f9d5fb"
},
"version" : {
"path" : "/",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

* Example 3: Acknowledge the deletion of a previously synchronized directory The server sends an <code>acknowledge</code> where the <code>newVersion</code> parameter is set to <code>null</code> to acknowledge the deletion of the previously synchronized directory version as found in the <code>version</code> parameter. The client should remove any stored entries for this directory from his local checksum store, and no longer send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests. Note that an acknowledged deletion of a directory implicitly acknowledges the deletion of all contained files and subfolders, too, so the client should also remove those <code>originalVersion</code>s from his local checksum store.
{
"action" : "acknowledge",
"version" : {
"path" : "/test",
"checksum" : "3525d6f28eb8cb30eb61ab7932367c35"
}
}

=== <code>edit</code> ===
Instructs the client to edit a file- or directory version. This is used for move/rename operations. The <code>version</code> parameter is set to the version as sent in the <code>clientVersions</code> array of the preceding <code>syncfiles</code>/</code>syncfolders</code> action. The <code>newVersion</code> contains the new name/path the client should use. Unless the optional boolean parameter <code>acknowledge</code> is set to <code>false</code> an <code>edit</code> action implies that the client updates its known versions store accordingly, i.e. removes the previous entry for <code>version</code> and adds a new entry for <code>newVersion</code>.
When editing a directory version, the client should implicitly take care to create any not exisiting subdirectories in the <code>path</code> of the <code>newVersion</code> parameter.
A concurrent client-side modification of the file/directory version can be detected by the client by comparing the current checksum against the one in the passed <code>newVersion</code> parameter.

* Example 1: Rename a file The server sends an <code>edit</code> action where the source file is encoded in the <code>version</code>, and the target file in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the name found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes.
{
"path" : "/",
"action" : "edit",
"newVersion" : {
"name" : "test_1.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
},
"version" : {
"name" : "test.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
}
}

* Example 2: Move a directory The server sends an <code>edit</code> action where the source directory is encoded in the <code>version</code>, and the target directory in the <code>newVersion</code> parameter. The client should move the directory identified by the <code>version</code> parameter to the path found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the directory in <code>version</code> should be updated, too, to reflect the changes.
{
"action" : "edit",
"newVersion" : {
"path" : "/test2",
"checksum" : "3addd6de801f4a8650c5e089769bdb62"
},
"version" : {
"path" : "/test1/test2",
"checksum" : "3addd6de801f4a8650c5e089769bdb62"
}
}

* Example 3: Rename a conflicting file The server sends an <code>edit</code> action where the original client file is encoded in the <code>version</code>, and the target filename in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the new filename found in the <code>newVersion</code> parameter. If the <code>acknowledge</code> parameter is set to <code>true</code> or is not set, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes, otherwise, as in this example, no changes should be done to the stored checksums.
{
"action" : "edit",
"version" : {
"checksum" : "fade32203220752f1fa0e168889cf289",
"name" : "test.txt"
},
"newVersion" : {
"checksum" : "fade32203220752f1fa0e168889cf289",
"name" : "test (TestDrive).txt"
},
"acknowledge" : false,
"path" : "/"
}

=== <code>download</code> ===
Contains information about a file version the client should download. For updates of existing files, the previous client version is supplied in the <code>version</code> parameter. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>download</code> request. The <code>totalLength</code> parameter is set to the file size in bytes, allowing the client to recognize when a download is finished. Given the supplied checksum, the client may decide on its own if the target file needs to be downloaded from the server, or can be created by copying a file with the same checksum to the target location, e.g. from a trash folder. The file's content type can be retrieved from the <code>contentType</code> parameter, similar to the file's creation and modification times that are availble in the <code>created</code> and <code>modified</code> parameters.

* Example 1: Download a new file The server sends a <code>download</code> action where the file version to download is encoded in the <code>newVersion</code> paramter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>. After downloading, the <code>newVersion</code> should be added to the client's known file versions database.
{
"totalLength" : 536453,
"path" : "/",
"action" : "download",
"newVersion" : {
"name" : "test.pdf",
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"
},
"contentType" : "application/pdf",
"created" : 1375276738232,
"modified" : 1375343720985
}

* Example 2: Download an updated file The server sends a <code>download</code> action where the previous file version is encoded in the <code>version</code>, and the file version to download in the <code>newVersion</code> parameter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>, replacing the previous file. After downloading, the <code>newVersion</code> should be added to the client's known file versions database, replacing an existing entry for the previous <code>version</code>.
{
"totalLength" : 1599431,
"path" : "/",
"action" : "download",
"newVersion" : {
"name" : "test.pdf",
"checksum" : "bb198790904f5a1785d7402b0d8c390e"
},
"contentType" : "application/pdf",
"version" : {
"name" : "test.pdf",
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"
},
"created" : 1375276738232,
"modified" : 1375343720985
}

=== <code>upload</code> ===
Instructs the client to upload a file to the server. For updates of existing files, the previous server version is supplied in the <code>version</code> parameter, and should be used for the following <code>upload</code> request. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>upload</code> request. When resuming a previously partly completed upload, the <code>offset</code> parameter contains the offset in bytes from which the file version should be uploaded by the client. If possible, the client should set the <code>contentType</code> parameter for the uploaded file, otherwise, the content type falls back to <code>application/octet-stream</code>.

=== <code>remove</code> ===
Instructs the client to delete a file or directory version. The <code>version</code> parameter contains the version to delete. A deletion also implies a removal of the corresponding entry in the client's known versions store.
A concurrent client-side modification of the file/directory version can be detected by comparing the current checksum against the one in the passed <code>version</code> parameter.

* Example 1: Remove a file The server sends a <code>remove</code> action where the file to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the file identified by the <code>version</code> parameter. A stored checksum entry for the file in <code>version</code> should be removed, too, to reflect the changes. The <code>newVersion</code> parameter is not set in the action.
{
"path" : "/test2",
"action" : "remove",
"version" : {
"name" : "test.txt",
"checksum" : "03395a94b57eef069d248d90a9410650"
}
}

* Example 2: Remove a directory The server sends a <code>remove</code> action where the directory to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the directory identified by the <code>version</code> parameter. A stored checksum entry for the directory in <code>version</code> should be removed, too, to reflect the changes.
{
"action" : "remove",
"version" : {
"path" : "/test1",
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"
}
}

=== <code>sync</code> ===
The client should trigger a synchronization of the files in the directory supplied in the <code>version</code> parameter using the <code>syncfiles</code> request. A <code>sync</code> action implies the client-side creation of the referenced directory if it not yet exists, in case of a new directory on the server.

If the <code>version</code> parameter is not specified, a synchronization of all folders using the <code>syncfolders</code> request should be initiated by the client.

If the <code>reset</code> flag in the <code>SYNC</code> action is set to <code>true</code>, the client should reset his local state before synchronizing the files in the directory. This may happen when the server detects a synchronization cycle, or believes something else is going wrong. Reset means that the client should invalidate any stored original checksums for the directory itself and any contained files, so that they get re-calculated upon the next synchronization. If the <code>reset</code> flag is set in a <code>SYNC</code> action without a apecific directory version, the client should invalidate any stored checksums, so that all file- and directory-versions get re-calculated during the following synchronizations.

* Example 1: Synchronize folder The server sends a <code>sync</code> action with a <code>version</code>. The client should trigger a <code>syncfiles</code> request for the specified folder.
{
"action": "sync",
"version": {
"path": "<folder>",
"checksum": "<md5>"
}
}

* Example 2: Synchronize all folders The server sends a <code>sync</code> action without <code>version</code> (or version is //null//). The client should trigger a <code>syncfolder</code> request, i.e. the client should synchronize all folders.
{
"action": "sync",
"version": null
}

=== <code>error</code> ===
With the <code>error</code> action, file- or directory versions causing a synchronization problem can be identified. The root cause of the error is encoded in the <code>error</code> parameter as described at the [[HTTP_API#Error_handling|HTTP API]].

Basically, there are two scenarios where either the errorneous version affects the synchronization state or not. For example, a file that was deleted at the client without sufficient permissions on the server can just be downloaded again by the client, and afterwards, client and server are in-sync again. On the other hand, e.g. when creating a new file at the client and this file can't be uploaded to the server due to missing permissions, the client is out of sync as long as the file is present. Therefore, the boolean parameter <code>quarantine</code> instructs the client whether the file or directory version must be excluded from the synchronization or not. If it is set to <code>true</code>, the client should exclude the version from the <code>clientVersions</code> array, and indicate the issue to the enduser. However, if the synchronization itself is not affected and the <code>quarantine</code> flag is set to <code>false</code>, the client may still indicate the issue once to the user in the background, e.g. as a balloontip notification.

The client may reset it's quarantined versions on it's own, e.g. if the user decides to "try again", or automatically after a configurable interval.

The server may also decide that further synchronization should be suspended, e.g. in case of repeated synchronization problems. Such a situation is indicated with the parameter <code>stop</code> set to <code>true</code>. In this case, the client should at least cancel the current synchronization cycle. If appropriate, the client should also be put into a 'paused' mode, and the user should be informed accordingly.

There may also be situations where a error or warning is sent to the client, independently of a file- or directory version, e.g. when the client version is outdated and a newer version is available for download.

The most common examples for errors are insufficient permissions or exceeded quota restrictions, see examples below.

* Example 1: Create a file in a read-only folder The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : ["/test"],
"error" : "You are not allowed to create files at \"/test\"",
"error_id" : "1358320776-69",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0012"
},
"path" : "/test",
"quarantine" : true,
"action" : "error",
"newVersion" : {
"name" : "test.txt",
"checksum" : "3f978a5a54cef77fa3a4d3fe9a7047d2"
}
}

* Example 2: Delete a file without sufficient permissions Besides a new <code>download</code> action to restore the locally deleted file again, the server sends an <code>error</code> action where the errorneous file is encoded in the <code>version</code> parameter and the <code>quarantine</code> flag is set to <code>false</code>. Further synchronizations are not affected, but the client may still inform the user about the rejected operation. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : ["test.png", "/test"],
"error" : "You are not allowed to delete the file \"test.png\" at \"/test\"",
"error_id" : "1358320776-74",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0011"
},
"path" : "/test",
"quarantine" : false,
"action" : "error",
"newVersion" : {
"name" : "test.png",
"checksum" : "438f06398ce968afdbb7f4db425aff09"
}
}

* Example 3: Upload a file that exceeds the quota The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.
{
"error" : {
"category" : 3,
"error_params" : [],
"error" : "The allowed Quota is reached",
"error_id" : "-485491844-918",
"categories" : "PERMISSION_DENIED",
"code" : "DRV-0016"
},
"path" : "/",
"quarantine" : true,
"action" : "error",
"newVersion" : {
"name" : "test.txt",
"checksum" : "0ca6033e2a9c2bea1586a2984bf111e6"
}
}

* Example 4: Synchronize with a client where the version is no longer supported. The server sends an <code>error</code> action with code <code>DRV-0028</code> and an appropriate error message. The <code>stop</code> flag is set to <code>true</code> to interrupt the synchronization cycle.
{
"stop" : true,
"error" : {
"category" : 13,
"error_params" : [],
"error" : "The client application you're using is outdated and no longer supported - please upgrade to a newer version.",
"error_id" : "103394512-13",
"categories" : "WARNING",
"code" : "DRV-0028",
"error_desc" : "Client outdated - current: \"0.9.2\", required: \"0.9.10\""
},
"quarantine" : false,
"action" : "error"
}

* Example 5: Synchronize with a client where a new version of the client application is available. The server sends an <code>error</code> action with code <code>DRV-0029</code> and an appropriate error message. The <code>stop</code> flag is set to <code>false</code> to indicate that the synchronization can continue.
{
"stop" : false,
"error" : {
"category" : 13,
"error_params" : [],
"error" : "A newer version of your client application is available for download.",
"error_id" : "103394512-29",
"categories" : "WARNING",
"code" : "DRV-0029",
"error_desc" : "Client update available - current: \"0.9.10\", available: \"0.9.12\""
},
"quarantine" : false,
"action" : "error"
}

== Synchronize folders ==

This request performs the synchronization of all folders, resulting in different actions that should be executed on the client afterwards. This operation typically serves as an entry point for a synchronization cycle.

PUT <code>/ajax/drive?action=syncfolders</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>version</code> - The current client version (matching the pattern <code>^[0-9]+(\\.[0-9]+)*$</code>). If not set, the initial version <code>0</code> is assumed.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request Body: 
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current directories below the root directory as a flat list, encoded as [[#Directory_Version|Directory Versions]]. The original versions array contains all previously known directories, i.e. all previously synchronized and acknowledged directories, also encoded as [[#Directory_Version|Directory Versions]].

Optionally, available since API version 2, the JSON object may also contain two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern|File patterns]] and [[#Directory_pattern|Directory patterns]] accordingly. See [[#Client_side_filtering|Client side filtering]] for details.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}, {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}
],
"originalVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}, {
"path" : "/test2",
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}
]
}

<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"version" : {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}
}
]
}

Example 2:
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}, {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}
],
"originalVersions" : [{
"path" : "/",
"checksum" : "7b744b13df4b41006495e1a15327368a"
}, {
"path" : "/test2/test3",
"checksum" : "c193fae995d9f9431986dcdc3621cd98"
}, {
"path" : "/test2",
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"
}, {
"path" : "/test1",
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"
}
]
"fileExclusions" : [{
"path" : "/",
"name" : "excluded.txt",
"type" : "exact"
}
], "directoryExclusions" : [{
"path" : "/temp",
"type" : "exact"
}, {
"path" : "/temp/*",
"type" : "glob"
}
]
}

<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"version" : {
"path" : "/test2",
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"
}
}
]
}

== Synchronize files in a folder ==

This request performs the synchronization of a single folder, resulting in different actions that should be executed on the client afterwards. This action is typically executed as result of a <code>syncfolders</code> action.

PUT <code>/ajax/drive?action=syncfiles</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>columns</code> (optional) - A comma-separated list of columns representing additional metadata that is relevant for the client. Each column is specified by a numeric column identifier. Column identifiers for file metadata are defined in [[#FileMetadata|File Metadata]]. If available, the requested metadata of files is included in the corresponding <code>DOWNLOAD</code> and <code>ACKNOWLEDGE</code> actions (deprecated, available until API version 2).
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.
* <code>driveMeta</code> (optional, available since API version 5) - Controls the <code>.drive-meta</code> synchronization mode: <code>true</code>/<code>false</code> to forcibly enable or disable metadata synchronization for the request, or <code>inline</code> to include <code>.drive-meta</code>-data inside a corresponding <code>DOWNLOAD</code> action as <code>data</code>-parameter if suitable.

Request Body: 
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current files in the client directory, encoded as [[#File_Version | File Versions]]. The original versions array contains all previously known files, i.e. all previously synchronized and acknowledged files, also encoded as [[#File_Version | File Versions]].

Optionally, available since API version 2, the JSON object may also contain an array named <code>fileExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern | File patterns]]. See [[#Client_side_filtering|Client side filtering]] for details.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>. If <code>driveMeta</code> was set to <code>inline</code>, <code>DOWNLOAD</code> actions for <code>.drive-meta</code> will carry the metadata in an additional JSON object in the corresponding action's parameters at <code>data</code>, if the <code>.drive-meta</code>-file is smaller than a certain threshold (the contents may still be requested with an explicit download then).

Example:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}, {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
],
"originalVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}
]
}

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
{
"data" : [{
"path" : "/test2",
"action" : "upload",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
},
"offset" : 0
}
]
}

Example 2:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
{
"clientVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}, {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
],
"originalVersions" : [{
"name" : "Jellyfish.jpg",
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"
}
]
"fileExclusions" : [{
"path" : "*",
"name" : "*.tmp",
"type" : "glob"
}
]
}

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
{
"data" : [{
"path" : "/test2",
"action" : "upload",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
},
"offset" : 0
}
]
}

Example 3:
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=123975&path=/&apiVersion=4&driveMeta=inline&session=0833ca06093a4bad826347a30bf7ace7
> Content:
{
"clientVersions": [],
"originalVersions": []
}

<== HTTP 200 OK (27.5238 ms elapsed, 2058 bytes received)
< Content:
{
"data": {
"actions": [{
"action": "download",
"newVersion": {
"checksum": "36301942a30c3c09bc59f6e9b0c63fba",
"name": ".drive-meta"
},
"totalLength": 1511,
"data": {
"id": "123975",
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"entity": 7,
"group": false
}],
"extended_permissions": [{
"entity": 7,
"bits": 403710016,
"type": "user",
"display_name": "Test User 2",
"contact": {
"email1": "test2@local.ox",
"last_name": "test2",
"first_name": "test2"
}
}],
"jump": ["permissions"],
"shareable": true,
"files": [{
"name": "test1.txt",
"created": 1460030191867,
"modified": 1460030191867,
"created_by": 7,
"modified_by": 7,
"content_type": "text/plain",
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=1600&height=1600",
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"edit",
"permissions",
"version_history"]
},
{
"name": "test2.txt",
"created": 1460030191931,
"modified": 1460030191931,
"created_by": 7,
"modified_by": 7,
"content_type": "text/plain",
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=1600&height=1600",
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"edit",
"permissions",
"version_history"]
}]
},
"path": "/",
"modified": 1460030191779
},
{
"action": "download",
"newVersion": {
"checksum": "e8d1be53d24895ae5cfc2808bec152bc",
"name": "test1.txt"
},
"totalLength": 36,
"created": 1460030191867,
"path": "/",
"modified": 1460030191867
},
{
"action": "download",
"newVersion": {
"checksum": "767c4efab82482dcfafdcdbc034800d4",
"name": "test2.txt"
},
"totalLength": 36,
"created": 1460030191931,
"path": "/",
"modified": 1460030191931
}]
}
}

== Download a file ==

Downloads a file from the server.

GET <code>/ajax/drive?action=download</code>

or

PUT <code>/ajax/drive?action=download</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to download.
* <code>checksum</code> - The checksum of the file version to download.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>offset</code> (optional) - The start offset in bytes for the download. If not defined, an offset of <code>0</code> is assumed.
* <code>length</code> (optional) - The number of bytes to include in the download stream. If not defined, the file is read until the end.

Request Body: 
Optionally, available since API version 3, if client-side file- and/or directory exclusion filters are active, a PUT request can be used. The request body then holds a JSON object containing two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[File_pattern|File patterns]] and [[Directory_pattern|Directory patterns]] accordingly. See [[Client_side_filtering|Client side filtering]] for details.

Response: 
The binary content of the requested file version. Note that in case of errors, an exception is not encoded in the default JSON error format here. Instead, an appropriate HTTP error with a status code != 200 is returned. For example, in case of the requested file being deleted or modified in the meantime, a response with HTTP status code 404 (not found) is sent.

Example:
==> GET http://192.168.32.191/ajax/drive?action=download&root=56&path=/test2&name=Jellyfish.jpg&checksum=5a44c7ba5bbe4ec867233d67e4806848&offset=0&length=-1&session=5d0c1e8eb0964a3095438b450ff6810f

<== HTTP 200 OK (20.0011 ms elapsed, 775702 bytes received)

== Upload a file ==

Uploads a file to the server.

PUT <code>/ajax/drive?action=upload</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>newName</code> - The target name of the file version to upload.
* <code>newChecksum</code> - The target checksum of the file version to upload.
* <code>name</code> (optional) - The previous name of the file version being uploaded. Only set when uploading an updated version of an existing file to the server.
* <code>checksum</code> - The previous checksum of the file version to upload. Only set when uploading an updated version of an existing file to the server.
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.
* <code>contentType</code> (optional) - The content type of the file. If not defined, <code>application/octet-stream</code> is assumed.
* <code>offset</code> (optional) - The start offset in bytes for the upload when resuming a previous partial upload. If not defined, an offset of <code>0</code> is assumed.
* <code>totalLength</code> (optional) - The total expected length of the file (required to support resume of uploads). If not defined, the upload is assumed completed after the operation.
* <code>created</code> (optional) - The creation time of the file as timestamp.
* <code>modified</code> (optional) - The last modification time of the file as timestamp. Defaults to the current server time if no value or a value larger than the current time is supplied.
* <code>binary</code> - Expected to be set to <code>true</code> to indicate the binary content.
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request body: 
The binary content of the uploaded file version.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=upload&root=56&path=/test2&newName=Penguins.jpg&newChecksum=9d377b10ce778c4938b3c7e2c63a229a&contentType=image/jpeg&offset=0&totalLength=777835&binary=true&device=Laptop&created=1375343426999&modified=1375343427001&session=5d0c1e8eb0964a3095438b450ff6810f
> Content:
[application/octet-stream;, 777835 bytes]

<== HTTP 200 OK (108.0062 ms elapsed, 118 bytes received)
< Content:
{
"data" : [{
"action" : "acknowledge",
"newVersion" : {
"name" : "Penguins.jpg",
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"
}
}
]
}

== Listen for changes (long polling) ==

Listens for server-side changes. The request blocks until new actions for the client are available, or an internal request timeout elapses. May return immediately if previously received but not yet processed actions are available for this client.

GET <code>/ajax/drive?action=listen</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.

Example:
==> GET http://192.168.32.191/ajax/drive?action=listen&root=65841&session=51378e29f82042b4afe4af1c034c6d68

<== HTTP 200 OK (63409.6268 ms elapsed, 28 bytes received)
< Content:
{
"data" : [{
"action" : "sync"
}
]
}

Alterantively, since API version 5, it's also possible to poll for changes in more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=listen</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to listen for changes in.

Response: 
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. The relevant root folder identifier is available in the <code>root</code> parameter of the action. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=listen&session=51378e29f82042b4afe4af1c034c6d68
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data" : [{
"action" : "sync",
"root" : "129137"
}
]
}

== Get quota ==

Gets the quota limits and current usage for the storage the supplied root folder belongs to. Depending on the filestore configuration, this may include both restrictions on the number of allowed files and the total size of all contained files in bytes. If there's no limit, -1 is returned.

GET <code>/ajax/drive?action=quota</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Response: 
A JSON object containing the quota restrictions inside a JSON array with the property name <code>quota</code>. The JSON array contains zero, one or two <code>quota</code> objects as described below, depending on the filestore configuration. If one or more quota <code>type</code>s are missing in the array, the client can expect that there are no limitations for that type. Besides the array, the JSON object also contains a hyperlink behind the <code>manageLink</code> parameter, pointing to an URL where the user could manage his quota restrictions.

{| id="Quota" cellspacing="0" border="1"
|+ align="bottom" | Quota
! Name !! Type !! Value
|-
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).
|-
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).
|-
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).
|}

Example:
==> GET http://192.168.32.191/ajax/drive?action=quota&root=56&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (9.6854 ms elapsed, 113 bytes received)
< Content:
{
"data" : {
"quota" : [{
"limit" : 107374182400,
"use" : 1109974882,
"type" : "storage"
}, {
"limit" : 800000000000,
"use" : 1577,
"type" : "file"
}
],
"manageLink" : "https://www.example.com/manageQuota"
}
}

== Get Settings ==

Gets various settings applicable for the drive clients.

GET <code>/ajax/drive?action=settings</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>language</code> (optional) - The locale to use for language-sensitive settings (in the format <code><2-letter-language>_<2-letter-region></code>, e.g. <code>de_CH</code> or <code>en_GB</code>). Defaults to the user's configured locale on the server.

Response: 
A JSON object holding the settings as described below. This also includes a JSON array with the property name <code>quota</code> that contains zero, one or two quota objects as described below, depending on the filestore configuration. If one or more quota types are missing in the array, the client can expect that there are no limitations for that type.

{| id="Quota" cellspacing="0" border="1"
|+ align="bottom" | Quota
! Name !! Type !! Value
|-
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).
|-
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).
|-
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).
|}

{| id="Settings" cellspacing="0" border="1"
|+ align="bottom" | Settings
! Name !! Type !! Value
|-
| helpLink || String || A hyperlink to the online help.
|-
| quotaManageLink || String || A hyperlink to an URL where the user could manage his quota restrictions.
|-
| quota || Array || A JSON array containing the quota restrictions as described above.
|-
| serverVersion || String || The server version string.
|-
| supportedApiVersion || String || The API version supported by the server.
|-
| minApiVersion || String || The API version required to synchronize with the server.
|-
| localizedFolderNames || Object || A JSON object mapping the (relative) paths of directories to their localized name (based on the supplied <code>language</code> or the user's locale). Available with v7.8.1.
|-
| capabilities || Array || A JSON array holding relevant capabilities of the user. Available with v7.8.1.
|}

Example:
==> GET http://192.168.32.191/ajax/drive?action=settings&root=56&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (11.3530 ms elapsed, 318 bytes received)
< Content:
{
"data" : {
"quota" : [{
"limit" : 107374182400,
"use" : 8828427,
"type" : "storage"
}, {
"limit" : 800000000000,
"use" : 1559,
"type" : "file"
}
],
"helpLink" : "http://192.168.32.191/appsuite/help-drive/l10n/de_DE/index.html",
"quotaManageLink" : "http://192.168.32.191/manageQuota",
"serverVersion" : "7.8.1-Rev1",
"supportedApiVersion" : "4",
"minApiVersion" : "1",
"localizedFolderNames": {
"/Documents": "Dokumente",
"/Music": "Musik",
"/Pictures": "Bilder",
"/": "Meine Dateien",
"/Documents/Templates": "Vorlagen"
},
"capabilities" : [
"invite_guests",
"share_links",
"invite_users_and_groups"
]
}
}

== Subscribe to Push-Events ==

Registers a client device to receive push notifications from the server. The subscription is performed based on the configured root folder ID of the client application that identifies itself with it's device token. Supported services currently include the Apple Push Notification Service (APN) and Google Cloud Messaging (GCM). Trying to perform an identical subscription (same <code>root</code>, <code>service</code> and <code>token</code>) from the same user account again is treated as a no-op.

GET <code>/ajax/drive?action=subscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=subscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (13.6268 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

Alterantively, since API version 5, a subscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=subscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to subscribe to.

Response: 
An empty JSON result.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=subscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Unsubscribe from Push-Events ==

Unregisters a previously registered client device to stop receiving push notifications from the server. The same parameters that were used to perform the subscription need to be passed again, which includes the root folder ID, the device token and the service name.

GET <code>/ajax/drive?action=unsubscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=unsubscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (26.0015 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

Alterantively, since API version 5, an unsubscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.

PUT <code>/ajax/drive?action=unsubscribe</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The device's registration token as assigned by the service.

Request Body:
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to unsubscribe from.

Response: 
An empty JSON result.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=unsubscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677
> Content:
{
"root": [ "129136", "129137" ]
},

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Update the subscription token ==

Updates a device's registration token in case a new one was assigned by the service.

GET <code>/ajax/drive?action=updateToken</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.
* <code>token</code> - The previous registration token as assigned by the service.
* <code>newToken</code> - The new registration token as assigned by the service.

Response: 
An empty JSON result.

Example:
==> GET http://192.168.32.191/ajax/drive?action=updateToken&service=apn&session=51378e29f82042b4afe4af1c034c6d68&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677&newToken=38919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677

<== HTTP 200 OK (15.6653 ms elapsed, 11 bytes received)
< Content:
{
"data" : {
}
}

== Get file metadata ==

Deprecated, available until API version 2. 
Additional metadata of synchronized files is made available via the <code>fileMetadata</code> request.

PUT <code>/ajax/drive?action=fileMetata</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>columns</code> - A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for file metadata are defined in [[#FileMetadata|File Metadata]].

Request Body: 
A JSON array containing the file versions to get the metadata for. Each object in the array should be sent as [[#File_Version | File Versions]], and needs to be present in the referenced path.

Response: 
A JSON array containing the file metadata in the order of the requested file versions. Each array element describes one file metadata and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

{| id="FileMetadataDeprecated" cellspacing="0" border="1"
|+ align="bottom" | File Metadata (deprecated)
! ID !! Name !! Type !! Value
|-
| name || String || The name of the file version.
|-
| 4 || created || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| 5 || modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| 702 || name || String || The name of the file, including it's extension, e.g. <code>test.doc</code>.
|-
| 703 || contentType || String || The file's content type, e.g. "image/png".
|-
| 708 || checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|-
| 750 || previewLink || String || A direct link to a medium-sized preview image of the file if available.
|-
| 751 || directLinkFragments || String | The fragments part of the direct link that can be used in combination with the [[http://oxpedia.org/index.php?title=HTTP_API#Token_Login_.28since_7.0.1.29 |token login]] method to jump directly to the detail view of the file in the web interface, bypassing the need to login manually.
|-
| 752 || directLink || String || A direct link to the detail view of the file in the web interface.
|-
| 753 || thumbnailLink || String || A direct link to a small thumbnail image of the file if available.
|}

Example:
==> PUT http://192.168.32.191/ajax/drive?action=fileMetadata&root=97974&path=%2f&columns=702%2c708%2c752%2c750%2c753&session=43aca91a80de42559ff0c2493dd973d0
> Content:
[
{
"name" : "image.jpg",
"checksum" : "2b04df3ecc1d94afddff082d139c6f15"
}, {
"name" : "song.mp3",
"checksum" : "5a9a91184e611dae3fed162b8787ce5f"
}, {
"name" : "test1.txt",
"checksum" : "7e36f409a042f06ecb88606a97a88c8f"
}, {
"name" : "test3.txt",
"checksum" : "703bc9aabff33faf07cf121dcda12ec8"
}
]

<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)
< Content:
[
["image.jpg", "2b04df3ecc1d94afddff082d139c6f15", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179629", "https://192.168.32.191/ajax/files?action=document&folder=97974&id=179629&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179629"],
["song.mp3", "5a9a91184e611dae3fed162b8787ce5f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179630", "https://192.168.32.191/ajax/image/file/mp3Cover?folder=97974&id=179630&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179630"],
["test1.txt", "7e36f409a042f06ecb88606a97a88c8f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179626", null, "m=infostore&f=97974&i=179626"],
["test3.txt", "703bc9aabff33faf07cf121dcda12ec8", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179624", null, "m=infostore&f=97974&i=179624"]
]

== Get a direct link for a folder/a file into appsuite ==

Available since API version 4. 

Generate a direct link into appsuite UI for a synchronized file/a synchronized folder and a token for token-based login.

POST <code>/ajax/drive?action=jump</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file in the synchronized folder given in <code>path</code>-parameter. Optional
* <code>method</code> - [[#Methods | Methods]]
* <code>authId</code> - Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
* <code>clientToken</code> - Client side identifier for accessing the session later. The value should be some token that is unique for every login request.

Methods: 
* <code>edit</code>: Open the file in appsuite editor or in text/spreadsheet (if available).
* <code>permissions</code>: Open the file's/folder's change-permission dialog.
* <code>version_history</code>: Open the file's version history summary.
* <code>preview</code>: Open the file's/folder's preview.

Response: 
A JSON array containing the direct link to the file/folder including a server token for token based login.

Example:
==> POST http://localhost/ajax/drive?action=jump&session=48a289898ad949faaa46c04e7fb422f5&root=9547&path=/path/to/file&name=file_to_edit.txt&method=edit&authId=41763584-8460-11e4-b116-123b93f75dba
> Content: clientToken=47d74b1c-81df-11e4-b116-123b93f75cba

<== HTTP 200 OK
< Content:
{
"data": {
"redirectUrl": "http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68"
}
}

== Use direct link and token with token-based login ==

Available since API version 4. 

Login to appsuite UI with token-based login via the link created with [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].

GET <code>[direct link]</code>

Parameters:
* <code>clientToken</code> – Client side identifier for accessing the session. The value must be the same as in [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].

Example:
==> GET http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68&clientToken=47d74b1c-81df-11e4-b116-123b93f75cba

<== HTTP 200 OK

== Get synchronizable Folders ==

Available since API version 4. 

Allows getting a list of folders that are available on the server for synchronization. This request should be used to build up a folder tree and let the user select the root synchronization folder(s).

GET <code>/ajax/drive?action=subfolders</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>parent</code> - The ID of the parent folder to get the subfolders for as read from a previously fetched directory metadata object. Optional; if not set, the root available root folders are returned.

Response: 
A JSON array holding metadata information for all subfolders as defined in [[#DirectoryMetadata | Directory Metadata]], with the <code>files</code> array being left out.

Example:
==> GET http://192.168.32.191/ajax/drive?action=subfolders&session=35cb8c2d1423480692f0d5053d14ba52

<== HTTP 200 OK (241.0252 ms elapsed, 966 bytes received)
< Content:
{
"data": [{
"id": "com.openexchange.file.storage.googledrive://1/",
"name": "Google Drive",
"path": "/Google Drive",
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
},
{
"id": "10",
"name": "Freigegebene Dateien",
"path": "/Freigegebene Dateien",
"created": 1224493261628,
"modified": 1417164170136,
"has_subfolders": true,
"own_rights": 1,
"permissions": [{
"bits": 1,
"group": true,
"entity": 0,
"display_name": "All users",
"guest": false
},
{
"bits": 1,
"group": true,
"entity": 2147483647,
"display_name": "Guests",
"guest": false
}],
"jump": ["permissions"],
"shared": true
},
{
"id": "15",
"name": "Öffentliche Dateien",
"path": "/Öffentliche Dateien",
"created": 1224493261628,
"modified": 1418383637250,
"has_subfolders": true,
"own_rights": 403709956,
"permissions": [{
"bits": 403709956,
"group": true,
"entity": 0,
"display_name": "All users",
"guest": false
},
{
"bits": 1,
"group": true,
"entity": 2147483647,
"display_name": "Guests",
"guest": false
}],
"jump": ["permissions"],
"shared": true
},
{
"id": "com.openexchange.file.storage.dropbox://1/",
"name": "Dropbox",
"path": "/Dropbox",
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
},
{
"id": "9542",
"name": "Meine Dateien",
"path": "/Meine Dateien",
"created": 1320230546147,
"modified": 1426764458823,
"default_folder": true,
"has_subfolders": true,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"jump": ["permissions"]
}]
}

== Get a share link ==

Available since API version 4. 

Creates a new or gets the previously created link for a file or folder that can be used to access the item in a browser by anyone. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=getLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to get the link for as described in [[#DriveShareTarget|Drive Share Target]].

Response: 
A JSON object containing details about the share link, including its URL, as described in [[HTTP_API#ShareLink|Share Link]]. Additionally, the current checksum of the share target is included (starting with v7.8.1).

{| id="DriveShareTarget" cellspacing="0" border="1"
|+ align="bottom" | Drive Share Target
! Name !! Type !! Value
|-
| name || String || (Optional) The name of the file, including its extension, e.g. <code>test.doc</code>. Not set if the target is a directory.
|-
| path || String || The path of the (file's parent) directory, relative to the root folder.
|-
| checksum || String || The MD5 hash of the file or directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.
|}

Example 1: Get the intial link for a file
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (311.8978 ms elapsed, 118 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": true,
"checksum": "bdf3bf1da3405725be763540d6601144"
}
}

Example 2: Get an already existing link for a file
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (78.0547 ms elapsed, 167 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": false,
"expiry_date": 1451606400000,
"password": "secret",
"checksum": "bdf3bf1da3405725be763540d6601144"
}
}

== Update a share link ==

Available since API version 4. 

Updates a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request Body: 
A JSON object as described in [[HTTP_API#ShareLink|Share Link]] containing the properties of the link to update, as well as the share target itself as described in [[#DriveShareTarget|Drive Share Target]]. Only modified fields should be set.

Response: 
A JSON object containing details about the share link, including its URL, as described in [[HTTP_API#ShareLink|Share Link]]. Additionally, the current checksum of the share target is included (starting with v7.8.1).

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144",
"password": "secret",
"expiry_date": 1451606400000
}

<== HTTP 200 OK (341.8978 ms elapsed, 218 bytes received)
< Content:
{
"data": {
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",
"is_new": false,
"checksum": "bdf3bf1da3405725be763540d6601144",
"password": "secret",
"expiry_date": 1451606400000
}
}

== Delete a share link ==

Available since API version 4. 

Deletes a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=deleteLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to delete the link for as described in [[#DriveShareTarget|Drive Share Target]].

Response: 
An empty JSON object.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=deleteLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144"
}

<== HTTP 200 OK (149.3251 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Send a share link ==

Available since API version 4. 

Sends a notification message for a share link to one or more recipients.

PUT <code>/ajax/drive?action=sendLink</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to send the link for as described in [[#DriveShareTarget|Drive Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by <code>null</code> values. Optionally, a custom notification message may be specified in a <code>message</code> property (otherwise, some default message is used).

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=sendLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/",
"name": "photo.jpg",
"checksum": "bdf3bf1da3405725be763540d6601144",
"recipients": [
["Otto Example", "otto@example.com"],
["Horst Example", "horst@example.org"]
]
}

<== HTTP 200 OK (260.9242 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Get shares ==

Available since API version 4. 

Gets all files and directories within the synchronized tree that are shared to others.

GET <code>/ajax/drive?action=shares</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Response: 
The metadata of the shared items as a JSON object holding two JSON arrays <code>files</code> and <code>directories</code> containing the metadata as defined in [[#FileMetadata|File Metadata]] and [[#Directory_Metadata|DirectoryMetadata]] respectively.

Example:
==> GET http://192.168.32.191/ajax/drive?action=shares&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542

<== HTTP 200 OK (191.2707 ms elapsed, 5339 bytes received)
< Content:
{
"data": {
"directories": [{
"id": "316770",
"name": "test",
"checksum": "bef03e92c3c675c1a6efddc831ac21b9",
"localized_name": "test",
"path": "/test",
"created": 1437989289761,
"modified": 1438176370780,
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
{
"bits": 135274497,
"entity": 8340,
"display_name": "Otto Example",
"email_address": "otto@example.com",
"type": "guest"
},
{
"bits": 257,
"entity": 16175,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_permissions": [{
"entity": 182,
"bits": 403710016,
"type": "user",
"display_name": "Mander, Jens",
"contact": {
"email1": "jens.mander@example.com",
"last_name": "Mander",
"first_name": "Jens"
}
},
{
"entity": 8340,
"bits": 135274497,
"type": "guest",
"display_name": "Otto Example",
"contact": {
"email1": "otto@example.com"
}
},
{
"entity": 16175,
"bits": 257,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/102b560404b3e96c9623be94b3d643829a46b117558d9ec9/31342f1f"
}],
"jump": ["permissions"],
"shared": true,
"shareable": true
},
{
"id": "300695",
"name": "sharetest",
"checksum": "cdfb5724f9614290a850ec507aea72a2",
"localized_name": "sharetest",
"path": "/sub1/check/sharetest",
"created": 1430218822598,
"modified": 1430218833769,
"own_rights": 403710016,
"permissions": [{
"bits": 257,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"type": "user"
},
{
"bits": 403710016,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
}],
"extended_permissions": [{
"entity": 10,
"bits": 257,
"type": "user",
"display_name": "Klaus Mander",
"contact": {
"email1": "klaus.mander@example.com",
"title": "",
"last_name": "Mander",
"first_name": "Klaus",
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"
}
},
{
"entity": 182,
"bits": 403710016,
"type": "user",
"display_name": "Mander, Jens",
"contact": {
"email1": "jens.mander@example.com",
"last_name": "Mander",
"first_name": "Jens"
}
}],
"jump": ["permissions"],
"shared": true,
"shareable": true
}],
"files": [{
"name": "Chrysanthemum.jpg",
"created": 1438177192835,
"modified": 1438177729597,
"created_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"modified_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"preview": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",
"thumbnail": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",
"object_permissions": [{
"bits": 1,
"entity": 16178,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_object_permissions": [{
"entity": 16178,
"bits": 1,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/1224dd0b065f2076b6db0e665f1f441f89f1308ad2a8ad7f/167e4881"
}],
"shared": true,
"shareable": true,
"jump": ["preview",
"permissions"],
"path": "/Pictures",
"checksum": "076e3caed758a1c18c91a0e9cae3368f"
},
{
"name": "data.zip",
"created": 1427291138800,
"modified": 1438593586254,
"created_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"modified_by": {
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"type": "user"
},
"object_permissions": [{
"bits": 4,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"type": "user"
},
{
"bits": 4,
"entity": 8338,
"display_name": "Horst Example",
"email_address": "horst@example.com",
"type": "guest"
},
{
"bits": 1,
"entity": 11224,
"display_name": "Guest",
"type": "anonymous"
}],
"extended_object_permissions": [{
"entity": 10,
"bits": 4,
"type": "user",
"display_name": "Klaus Mander",
"contact": {
"email1": "klaus.mander@example.com",
"title": "",
"last_name": "Mander",
"first_name": "Klaus",
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"
}
},
{
"entity": 8338,
"bits": 4,
"type": "guest",
"display_name": "Horst Example",
"contact": {
"email1": "horst@example.com"
}
},
{
"entity": 11224,
"bits": 1,
"type": "anonymous",
"share_url": "http://127.0.0.1/ajax/share/1f74962e0b55529663dfbc3b55794ea59b753c9301c0da75/76c846ae"
}],
"shared": true,
"shareable": true,
"jump": ["permissions"],
"path": "/Projects/ACME",
"checksum": "d63540e8f986ec305b0dd1293d8a3276"
}]
}
}

== Get directory metadata ==

Available since API version 4. 

Gets metadata of a specific synchronized directory.

GET <code>/ajax/drive?action=getFolder</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the directory to update, relative to the root folder.
* <code>checksum</code> - The checksum of the directory to update.

Response: 
A JSON object representing the requested directoy metadata as described in [[#DirectoryMetadata|Directory Metadata]].

== Get file metadata ==

Available since API version 4. 

Gets metadata of a specific synchronized file.

PUT <code>/ajax/drive?action=getFile</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to update.
* <code>checksum</code> - The checksum of the file version to update.

Response: 
A JSON object representing the requested directory metadata as described in [[#FileMetadata|File Metadata]].

== Update directory metadata ==

Available since API version 4. 

Updates specific metadata of a synchronized directory. This currently only includes the permissions - which in turn is only allowed for folders marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateFolder</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the directory to update, relative to the root folder.
* <code>checksum</code> - The checksum of the directory to update.

Request body: 
A JSON object named <code>folder</code> describing the updated folder metadata as described in [[HTTP_API#DetailedFolderData|Detailed Folder Data]]. Currently, only the property <code>permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e
> Content:
{
"folder": {
"permissions": [{
"group": false,
"bits": 403710016,
"entity": 182
},
{
"type": "guest",
"email_address": "otto@example.com",
"display_name": "Otto Example",
"bits": 135274497
}]
},
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (207.1722 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Update file metadata ==

Available since API version 4. 

Updates specific metadata of a synchronized file. This currently only includes the object permissions - which in turn is only allowed for files marked as <code>shareable</code>.

PUT <code>/ajax/drive?action=updateFile</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.
* <code>path</code> - The path to the synchronized folder, relative to the root folder.
* <code>name</code> - The name of the file version to update.
* <code>checksum</code> - The checksum of the file version to update.

Request body: 
A JSON object named <code>file</code> describing the updated file metadata as described in [[HTTP_API#DetailedInfoitemData|Detailed Infoitem Data]]. Currently, only the property <code>object_permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e
> Content:
{
"file": {
"object_permissions": [{
"type": "guest",
"email_address": "otto@example.com",
"display_name": "Otto Example",
"bits": 16641
}]
},
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

== Notify about shared items ==

Available since API version 4. 

(Re-)Sends a share notification to one or more permission entities of a specific shared file or folder.

PUT <code>/ajax/drive?action=notify</code>

Parameters:
* <code>session</code> - A session ID previously obtained from the login module.
* <code>root</code> - The ID of the referenced root folder on the server.

Request body: 
A JSON object describing the target file- or directory version to send the notification for as described in [[#DriveShareTarget|Drive Share Target]]. The entity IDs of the recipients are listed in the JSON array named <code>entities</code>. Optionally, an additional JSON object <code>notification</code> may be included, inside of which a custom <code>message</code> can be passed (otherwise, some default message is used).

Response: 
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.

Example:
==> PUT http://192.168.32.191/ajax/drive?action=notify&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542
> Content:
{
"path": "/test",
"name": "image.jpg",
"checksum": "d63540e8f986ec305b0dd1293d8a3276",
"entities": [10,78],
"notification": {
"message": "Look!"
}
}

<== HTTP 200 OK (45.2084 ms elapsed, 11 bytes received)
< Content:
{
"data": {}
}

= File- and Directory Name Restrictions =

Regarding the case sensitivity of file and directory names, OX Drive works in a case-insensitive, but case-preserving way. That means that there cannot be two files with an equal name ignoring case in the same directory, but it's still possible to synchronize the names in a case-sensitive manner, as well as it's possible to change only the case of file- and directory names.

The same applies to equally named files and directories on the same level in the folder hierarchy, i.e. it's not possible to create a new file in a directory where an equally (ignoring case) named subdirectory already exists and vice versa.

There is a similar restriction regarding file and directory names in the same directory having different unicode normalization forms, yet the same textual representation. OX Drive requires uniqueness regarding this textual representaion of potentially different encoded unicode strings. So, in case the client tries to synchronize two textually equal files or directories, he is instructed to put one of them into quarantine. Internally the server performs an equals-check of the "NFC" normalization forms of the strings, i.e. an unicode string is normalized using full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. Details regarding unicode normalization can be found at http://www.unicode.org/reports/tr15/tr15-23.html .

== Invalid and ignored Filenames ==

There are some filenames that are invalid or ignored and therefore not synchronized. This means that files with these names should not be taken into account when sending the directory contents to the server, or when calculating the directory checksum (see below). The following list describes when a filename is considered invalid:
* If it contains one or of the following reserved characters:
** <code><</code> (less than),
** <code>></code> (greater than)
** <code>:</code> (colon)
** <code>"</code> (double quote)
** <code>/</code> (forward slash)
** <code>\</code> (backslash)
** <code>|</code> (vertical bar or pipe)
** <code>?</code> (question mark)
** <code>*</code> (asterisk)
** Characters whose integer representations are in the range from 0 through 31
* The last character is a <code>.</code> (dot) or <code>' '</code> (space)
* It's case-invariant name without an optional extension matches one of the reserved names <code>CON</code>, <code>PRN</code>, <code>AUX</code>, <code>NUL</code>, <code>COM1</code>, <code>COM2</code>, <code>COM3</code>, <code>COM4</code>, <code>COM5</code>, <code>COM6</code>, <code>COM7</code>, <code>COM8</code>, <code>COM9</code>, <code>LPT1</code>, <code>LPT2</code>, <code>LPT3</code>, <code>LPT4</code>, <code>LPT5</code>, <code>LPT6</code>, <code>LPT7</code>, <code>LPT8</code>, or <code>LPT9</code>
* It consists solely of whitespace characters

The following list gives an overview about the ignored filenames:
* <code>desktop.ini</code>
* <code>Thumbs.db</code>
* <code>.DS_Store</code>
* <code>icon\r</code>
* Any filename ending with <code>.drivepart</code>
* Any filename starting with <code>.msngr_hstr_data_</code> and ending with <code>.log</code>

Nevertheless, if the client still insists to send a file version with an invalid or ignored filename, the file creation on the server is refused with a corresponding <code>error</code> action (see below).

== Invalid and ignored Directory Names ==

There are also similar restrictions regarding invalid directory names. Any try to include them in the list of directory versions will be responded with a corresponding error action for the directory version. The following list describes when a path is considered invalid:
* If it contains one or of the following reserved characters:
** <code><</code> (less than),
** <code>></code> (greater than)
** <code>:</code> (colon)
** <code>"</code> (double quote)
** <code>\</code> (backslash)
** <code>|</code> (vertical bar or pipe)
** <code>?</code> (question mark)
** <code>*</code> (asterisk)
** Characters whose integer representations are in the range from 0 through 31
* The last character of any subpath (i.e. the last part of the whole path or the part preceding the spearator character <code>/</code>) is a <code>.</code> (dot) or <code>' '</code> (space)
* It consists solely of whitespace characters
* It not equals the root path <code>/</code>, but ends with a <code>/</code> (forward slash) character
* It contains two or more consecutive <code>/</code> (forward slash) characters

The following list gives an overview about the ignored directory names:
* <code>/.drive</code>
* Any directory whose path ends with <code>/.msngr_hstr_data</code>

== Length Restrictions ==

The maximum allowed length for path segments, i.e. the parts between forawrd slashes (</code>/</code>) in directory and filenames, is restricted to 255 characters. Synchronizing a file or directory version that contains path segments longer than this limit leads to those versions being put into quarantine.

= Client side filtering =

Client-side filtering is available since API version 2. 

OX Drive clients may define a user- and/or application-defined list of file- and directory name exclusions. Those exclusion filters are then taken into account during synchronization, i.e. files and directories matching a defined exclusion pattern are ignored when comparing the list of server-, client- and original versions. Also, the file exclusion lists are considered for the calculation of aggergated directory checksums.

The exclusion filters may be set, changed or unset at any time during synchronization, there are no additional requests needed to set them up. Instead, the list of excluded files and directories is simply sent along with each <code>syncFolders</code>, <code>syncFiles</code> and <code>download</code> request. The following tables show the JSON representation of file- and directory patterns that are used to build up the exlcusion lists:

== Directory pattern ==

A directory pattern is defined by a pattern string and further attributes.

{| id="DirectoryPattern" cellspacing="0" border="1"
|+ align="bottom" | Directory Pattern
! Name !! Type !! Value
|-
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>.
|-
| path || String || The path pattern, in a format depending on the pattern type.
|-
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code>
|}

== File pattern ==

A file pattern is defined by pattern strings for the filename and path, as well as further attributes.

{| id="FilePattern" cellspacing="0" border="1"
|+ align="bottom" | File Pattern
! Name !! Type !! Value
|-
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>.
|-
| path || String || The path pattern, in a format depending on the pattern type.
|-
| name || String || The filename pattern, in a format depending on the pattern type.
|-
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code>
|}

== Pattern types ==

A pattern currently may be defined in two formats: <code>exact</code> or <code>glob</code>.

* <code>exact</code> An exact pattern, matching the file- or directory version literally. For example, to exclude the file <code>Backup.pst</code> in the subfolder <code>Mail</code> below the root synchronization folder, an <code>exact</code> file pattern would look like: <code>{"path":"/Mail","name":"Backup.pst","type":"exact"}</code>, or, an <code>exact</code> directory pattern for the directory <code>/Archive</code> would be represented as <code>{"path":"/Archive","type":"exact"}</code>.
* <code>glob</code> A simple pattern allowing to use the common wildcards <code>*</code> and <code>?</code> to match file- and directory versions. For example, to exclude all files ending with <code>.tmp</code> across all directories, the <code>glob</code> file pattern could be defined as <code>{"path":"*","name":"*.tmp","type":"glob"}</code>, or, to exclude the directory <code>/Project/.git</code> and all its subdirectories recursively, this would be expressed using a combination of the following two directory patterns: <code>[{"path":"/Project/.git","type":"exact"},{"path":"/Project/.git*","type":"glob"}]</code>.

== Further considerations ==

* It's possible to exclude a (parent) directory with an appropriate pattern, while still subfolders below that directory being synchronized. This usually results in the excluded directory being created ob both client- and server side, but no file contents within the excluded directory being exchanged. If subfolders should be excluded, too, a wildcard should be used in the pattern to match any subdirectories.
* If the client tries to synchronize a file- or directory version that is ignored, i.e. a version that would match any of the provided exclusion filters, the server behaves similarly to the handling of invalid and ignored file- and directory names (see above), i.e. the client would be instructed to put those versions into quarantine.
* For the calculation of directory checksums, it's important that the server and client perform exactly the same matching for ignored filenames: A <code>*</code> character matches zero or more characters, a <code>?</code> character matches exactly one character. All other characters are matched literally. Advanced glob flavors like braces to define subpattern alternatives or square brackets for character sets are not used.
* Client-side filtering is available with API version 2. The API version that is supported by the server is included in the response of the [[#Get Settings | Settings]] request.
* Whenever there are active exclusion filters, the <code>syncFolders</code> request should contain all of both directory and file exclusion filter lists. For the <code>syncFiles</code> request, it's sufficient to include the list of file exclusions.

= Metadata Synchronization =

The synchronization of metadata is available since API version 3. 

== Introduction ==

Previously, only the "raw" folders and files were synchronized between server and clients. While this is sufficient for basic synchronization, there are cases where the clients could benefit from additional data - "metadata" - that is already available on the server. For example, clients could display directories that have been shared or published to other people in a different way. Or, clients could consider folder permissions directly in case the user is performing a local change that would be rejected by the server in the next synchronization cycle anyway.

To supply the clients with those additional information without any influence on the existing synchronization protocol (!), <code>.drive-meta</code> files are introduced for each synchronized directory. Regarding synchronization, such files are treated like any other ordinary file. Especially, those files are taken into account when it comes to directory checksum calculation. Doing so, metadata updates result in a changed <code>.drive-meta</code> file, which in turn causes the parent directory checksum to change, hence synchronization is triggered.

However, some special handling applies for those files:

* Clients are not allowed to change metadata, so modifications of metadata files or the deletion of them is rejected. Recovery is done via the protocol here, i.e. the client is instructed to re-download the file.
* <code>.drive-meta</code> files are actually not stored physically on the file storage backend, but created on the fly based on the actual metadata of the directory.
* Client applications may either store such files on the client file system, or evaluate and store the contained metadata information in a local database for later retrieval. If the file is not saved physically on the client (which is actually recommended), the client is responsible to consider the metadata file in a virtual way and include it's checksum for the directory checksum calculation - similar to the server's internal handling.

Note: Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.

== Metadata format ==

The metadata in <code>.drive-meta</code> files is serialized in JSON format to allow easy processing at the clients. The following shows an example of the contents:
{
"path": "/",
"localized_name": "Meine Dateien",
"own_rights": 403710016,
"permissions": [{
"bits": 403710016,
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
}],
"shareable": true,
"jump": ["permissions"],
"files": [{
"name": "Koala.jpg",
"created": 1418024190565,
"modified": 1418026995663,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",
"thumbnail": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",
"object_permissions": [{
"bits": 1,
"group": false,
"entity": 10,
"display_name": "Klaus Mander",
"email_address": "klaus.mander@example.com",
"guest": false
},
{
"bits": 1,
"group": false,
"entity": 8338,
"email_address": "horst@example.com",
"guest": true
}],
"shareable": true,
"shared": true,
"number_of_versions": 1,
"version": "1",
"jump": ["preview",
"permissions",
"version_history"]
},
{
"name": "test.txt",
"created": 1418024198520,
"modified": 1418027394897,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=800&height=800",
"thumbnail": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=100&height=100",
"locked": true,
"shareable": true,
"number_of_versions": 4,
"version": "6",
"version_comment": "Uploaded with OX Drive (TestDrive)",
"versions": [{
"name": "test.txt",
"file_size": 23,
"created": 1418024198520,
"modified": 1418024202878,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "1",
"version_comment": "Uploaded with OX Drive (TestDrive)"
},
{
"name": "test.txt",
"file_size": 54,
"created": 1418024234782,
"modified": 1418024231522,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "2",
"version_comment": "Uploaded with OX Drive (TestDrive)"
},
{
"name": "test.txt",
"file_size": 120,
"created": 1418027349026,
"modified": 1418027355957,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "5"
},
{
"name": "test.txt",
"file_size": 127,
"created": 1418027370051,
"modified": 1418027366945,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"version": "6",
"version_comment": "Uploaded with OX Drive (TestDrive)"
}],
"jump": ["preview",
"edit",
"permissions",
"version_history"]
},
{
"name": "Kalimba.mp3",
"created": 1418026529047,
"modified": 1247549551659,
"created_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"modified_by": {
"group": false,
"entity": 182,
"display_name": "Mander, Jens",
"email_address": "jens.mander@example.com",
"guest": false
},
"preview": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=800&height=800",
"thumbnail": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=100&height=100",
"shareable": true,
"number_of_versions": 1,
"version": "1",
"version_comment": "Uploaded with OX Drive (TestDrive)",
"jump": ["preview",
"permissions",
"version_history"]
}]
}

The following objects describe the JSON structure of the metadata for a directory:

{| id="DirectoryMetadata" cellspacing="0" border="1"
|+ align="bottom" | Directory Metadata
! Name !! Type !! Value
|-
| id || String || The server-side unique identifier of the directory.
|-
| localized_name || String || The localized display name of the directory, if different from the physical name.
|-
| checksum || String || The directory's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| own_rights || Number|| Folder permissions which apply to the current user, as described in [[HTTP_API#PermissionFlags | Permission Flags]].
|-
| permissions || Array || All folder permissions, each element is an object as described in [[HTTP_API#PermissionObject | Permission Object]].
|-
| extended_permissions || Array || All folder permissions including some additional information, each element is an object as described in [[HTTP_API#ExtendedPermissionObject | Extended Permission Object]].
|-
| default_folder || Boolean || <code>true</code> if the folder is a default folder, <code>false</code> or not set, otherwise.
|-
| has_subfolders || Boolean || <code>true</code> if the folder (potentially) has subfolders, <code>false</code> or not set, otherwise.
|-
| shared || Boolean || <code>true</code> if the folder is shared, <code>false</code> or not set, otherwise.
|-
| shareable || Boolean || <code>true</code> if the folder can be shared to others by the user, <code>false</code> or not set, otherwise.
|-
| not_synchronizable || Boolean || <code>true</code> if the folder is exluded from synchronization, <code>false</code> or not set, otherwise.
|-
| type || Number || The special folder type, or not set, if not available.
|-
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the folder.
|-
| files || Array || Metadata for the contained files, each element is an object as described in [[#FileMetadata | File Metadata]]. Only set if metadata is retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|}

{| id="FileMetadata" cellspacing="0" border="1"
|+ align="bottom" | File Metadata
! Name !! Type !! Value
|-
| name || String || The name of the file the metadata belongs to.
|-
| checksum || String || The file's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| path || String || The path of the parent directory. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].
|-
| created || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time).
|-
| created_by || Number || User ID of the user who created this object.
|-
| modified_by || Number || User ID of the user who last modified this object.
|-
| content_type || String || The content type of the file.
|-
| preview || String || A URL to a preview image for the file.
|-
| thumbnail || String || A URL to a thumbnail image for the file.
|-
| object_permissions || Array || All file permissions, each element is an object as described in [[#HTTP_API#ObjectPermissionObject | Object Permission Object]].
|-
| extended_object_permissions || Array || All file permissions including some additional information, each element is an object as described in [[HTTP_API#ExtendedObjectPermissionObject | Extended Object Permission Object]].
|-
| shared || Boolean || <code>true</code> if the file is shared, <code>false</code> or not set, otherwise.
|-
| shareable || Boolean || <code>true</code> if the file can be shared to others by the user, <code>false</code> or not set, otherwise.
|-
| locked || Boolean || <code>true</code> if the file is locked, <code>false</code> or not set, otherwise.
|-
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the file.
|-
| number_of_versions || Number | The number of all versions of the file.
|-
| version || String || The current version identifier (usually, but not necessarily a numerical value) of the file.
|-
| version_comment || String | An additional comment for the file version.
|-
| versions || Array || Metadata for all versions of the file, each element is an object as described in [[#File_Version | File Version]].
|}

{| id="FileVersion" cellspacing="0" border="1"
|+ align="bottom" | File Version
! Name !! Type !! Value
|-
| name || String || The name of the file version.
|-
| file_size || Number || The file size of the version in bytes.
|-
| created || Timestamp || The file version's last modification time (always UTC, not translated into user time).
|-
| modified || Timestamp || The file version's last modification time (always UTC, not translated into user time).
|-
| created_by || Number || User ID of the user who created this object.
|-
| modified_by || Number || User ID of the user who last modified this object.
|-
| version || String || The version identifier (usually, but not necessarily a numerical value) of the file version.
|-
| version_comment || String || An additional comment for the file version.
|}

== Client-side implementation ==

In order to make use of the metadata, clients should roughly implement the following:
* Include the <code>apiVersion</code> parameter in each request, and set it to at least <code>3</code> in order to include <code>.drive-meta</code> during synchronization
* Evaluate <code>.drive-meta</code> files and store the information, as well as the file's checksums in a local database
* Include this file in the calculation of the parent directory checksum, just like an ordinary file in that directory
* Do something useful with the metadata information.

== Additional notes ==

* The metadata synchronization via <code>.drive-meta</code> files embedded into the synchronization protocol obsoletes the previously used methods to receive metadata information ([[#Get_file_metadata]] and <code>columns</code> parameter in [[#Synchronize_files_in_a_folder]].
* Depending on the underlying file storage backend, the included metadata may vary, so each information should be treatened as optional.
* Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.

== Possible use cases ==
* For files where the <code>locked</code> property is <code>true</code>, display some kind of "lock" icon (-overlay) in the file list / explorer view
* For files or folders where the <code>shared</code> property is <code>true</code>, display some kind of "cloud" icon (-overlay) in the file list / explorer view
* For files or folders where the user is not allowed to perform an action with, don't offer such actions (e.g. if a file cannot be deleted or renamed by the user due to insufficient permissions, disable the corresponding options)
* Use the URLs in <code>preview</code> and <code>thumbnail</code> to get a preview image for the files
* Display the server creation / last modification timestamps of files and folders
* Embed a version history for files with multiple versions
* Show to which users a file or folder is currently shared
* Offer appropriate "jump" actions to the groupware web interface for more advanced options (e.g. to directly edit an .xlsx file in the spreadsheet application of the web interface, or to manage a folder's permission