Reserve File
/documents/api/1.2/files/{fileId}/reserve
Reserve the specified file. A file reservation lets other users (or processes) know that the file is in use.
Request
- application/json
- application/xml
-
fileId: string
Globally unique identifier (GUID) for the file.
-
dAccessCode(optional): string
Access code needed to use protected public links. It needs to be sent as part of a Cookie header in the following format:
dAccessCode-<linkID>=<passcodeValue>
-
linkID(optional): string
Public link ID of a public link authorizing the current user to access this file. To work, this public link must have the contributor role granted. It can be used as linkID or LinkID.
Response
- application/json
- application/xml
200 Response
The request was fulfilled.
object
-
errorCode(optional):
number
An error code of zero (0) indicates no errors.
-
id(optional):
string
Globally unique identifier (GUID) for the file.
-
reservationDate(optional):
string
Globally unique identifier (GUID) for the parent folder. If the parent folder is the user's home folder, the value for
.parentID
isself
. -
reservedBy(optional):
object User
User information
-
type(optional):
string
Item type
file
.
object
-
displayName(optional):
string
The display name for the user.
-
id(optional):
string
Globally unique identifier (GUID) for the user.
-
loginName(optional):
string
The login name for the user.
-
type(optional):
string
Item type
user
.
{
"id":"D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD",
"reservationDate":"2015-06-15T19:34:17.000Z",
"reservedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"type":"file",
"errorCode":"0"
}
403 Response
Forbidden if the user does not have read permission.
404 Response
File ID is not found.
Examples
The following example reserves the specified file.
POST .../files/D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD/reserve
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "errorCode": "0", "id": "D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD", "reservationDate": "2015-06-15T19:34:17Z", "reservedBy": { "displayName": "User AA", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "loginName": "userAALoginName", "type": "user" }, "type": "file" }
Example 2
The following example reserves the specified file. The example uses a public link ID because this file is under a folder structure not owned by or shared with the current user.
POST .../files/D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD/reserve
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "errorCode": "0", "id": "D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD", "reservationTime": "2016-06-30T21:16:22Z", "reservedBy": { "displayName": "User BB", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "loginName": "userBBLoginName", "type": "user" }, "type": "file" }
Example 3
The following example reserves the specified file. The example uses a public link ID protected by an access code because this file is under a folder structure not owned by or shared with the current user. An access code (test12345
) is submitted as part of a Cookie in the request header.
POST .../files/D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD/reserve
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518 Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345
Request Body
None.
HTTP Status Code
HTTP_STATUS = 200
JSON Response
{ "errorCode": "0", "id": "D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD", "reservationTime": "2016-06-30T21:16:22Z", "reservedBy": { "displayName": "User BB", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "loginName": "userBBLoginName", "type": "user" }, "type": "file" }
Example 4
The following example requests reservation of the specified file. Because this file is under a folder structure not owned by or shared with the current user, an access denied error message is returned.
POST .../files/D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD/reserve
Request Header
None.
Request Body
None.
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "errorCode": "-20", "errorKey": "!csFldCouldNotSetReservation!csCloudItemInsufficientPrivileges,User BB,fFileGUID:D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD,FLD_SET_RESERVATION", "errorMessage": "Could not set reservation. User 'User BB' has insufficient privilege to access fFileGUID:D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD with service FLD_SET_RESERVATION.", "id": "D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD", "title": "Could not set reservation. User 'User BB' has insufficient privilege to access fFileGUID:D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD with service FLD_SET_RESERVATION.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
Example 5
The following example requests reservation of the specified file. This file is under a folder structure not owned by or shared with the current user, and only a public link protected by an access code is available. An error is returned because the access code was not submitted as part of the request.
POST .../files/D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD/reserve
Request Header
LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
Request Body
None.
HTTP Status Code
HTTP_STATUS = 403
JSON Response
{ "errorCode": "-18", "errorKey": "!csFldCouldNotSetReservation!csAccessCodeRequiredForLinkAccess", "errorMessage": "Could not set reservation. The access code must be provided to access the link.", "id": "D5B8B54BA8C121BEDB91A1341212FF6185DEA5EFC0BD", "title": "Could not set reservation. The access code must be provided to access the link.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }