Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Enterprise Mobility Server 3.8
  3. Docs REST API
  4. REST API
  5. REST functions
  6. Document-related functions

Document-related functions

Function
REST Call URI
Verb
Description
Download document
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with-path
}
GET
This function downloads the document content to the client. 
The content type is not sent to the client.
Supported output HTTP headers:
  • ETag: This value provides the unique identifier for the current version of the data (file). 
  • Last-Modified: This value specifies the system last modified time for a file. 
  • Accept-Ranges: The server informs the client that it supports the range requests. 
  • Content-Length: The server returns a byte range to the client when responding to a range request. 
For chunked and resumable downloads, the following HTTP headers are optional:
  • Input HTTP request headers:
    • Range: This value specifies the range of bytes for the client to download. 
    • If-Range: This value tells the server to check if the content has changed from the initial download when a downloaded is resumed. If it changed, the entire document is returned. If it hasn't changed, only the requested section of the document is returned. The ETag must match the Range. 
  • Output HTTP response headers:
    • Content-Range: This value specifies the byte range returned.
Optional parameters:
  • storagePath* 
  • unprotected=true: This parameter specifies if unprotected contents of an RMS protected document are sent to the client. 
List documents
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
folder-path
}
GET
This function lists the documents in the specified folder. 
Optional parameters:
  • recurse: This parameter specifies whether to include the folders and subfolders.
  • maxitems: This parameter specifies a value for the maximum number of items to output. By default, when maxitems is not specified it is 10,000. 
  • view: This parameter specifies the 
    SharePoint
     view name used when the library or folder contents are retrieved.
  • sort: This parameter specifies whether to sort the list output. If the sort parameter is added, use the following format: "sort=
    field-name
     
    direction
    ".
    • The 
      field-name
       can be name, modified, or size.
    • The 
      direction
       can be asc or desc. By default, when direction is not specified, it is asc.
  • storagePath**
  • For chunked listing such as paging, the following parameters can be used:
    • startIndex: This parameter specifies the starting index of items.
    • endIndex: This parameter specifies the ending index of items.
    • refresh: This parameter specifies to delete the cached content when contents are cached.
  • Output HTTP response header:
    • X-Good-Content-Range: items startIndex-endIndex/numberOfItems 
  • filter: This parameter specifies to filter the list output to only display files or folders. If adding the filter parameter, use the format: "filter=file|folder". By default, the output is not filtered and both files and folders are displayed.
  • format: This parameter specifies to format the list output to flat or nested. If you add the format parameter, use the format: "format=flat|nested". By default the format is nested.
    To use the format option, you must specify recurse=true. If recurse=true and the format is specified as flat, then the "Folder Contents" JSON key in the folders are removed and a "path" JSON key value is added for each file and folder. All of the nested files and folders are displayed at the same level.
Paging and recursion cannot be specified in the same request if the format is specified as nested.
Upload document
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-­with‐path
}
PUT
This function uploads the document to the Share or 
SharePoint
 server. 
The document contents are sent as the JSON body.
  • If the file already exists, it is replaced. 
  • If the path does not fully exist, the required folders are created.
Optional parameters:
  • storagePath*
Create Folder
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
folder-path
}/
PUT
This function creates a folder. If a trailing slash is added to the end of the file path, the function automatically creates any intermediate folders if they do not exist.
Optional parameters:
  • storagePath**
Delete document
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with‐path
}
DELETE
This function deletes the specified document.
Optional parameters:
  • storagePath*
Delete folder
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
folder‐path
}?recurse
DELETE
This function deletes the specified folder if the folder contents are empty. 
Optional parameters:
  • recurse: This is required to delete a folder and its content.
Retrieve document metadata
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with-path
}?metadata
GET
This function returns document metadata.
Optional parameters:
  • storagePath**
  • includeRMSPermissions=true: This parameter specifies whether RMS permissions information is included when the document is Rights Management Services (RMS) protected.  
Retrieve folder metadata
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
folder-path
}?metadata
GET
This function returns folder metadata. If the folder has views associated with them, then these are returned. 
Optional parameters:
  • storagePath**
For an example of retrieved folder metadata output, see SharePoint library metadata retrieval.
Parse storage path
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}?parse&path={
storage-path
}
GET
This function parses the storage path. 
Optional parameters:
  • storage: This parameter specifies the underlying storage (for example, FileShare or 
    SharePoint
    ).
Move File
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with-path
}?action=move
POST
This function moves a file to a new location.
The required request body is JSON, as shown in the following example: 
{
 "targetPath":"target-path",
 "overwrite":"true" Or "false",
 "keepOriginal":"true" Or "false"
}
  • The 
    targetPath
     (string) value is the path relative to repository path where the file needs to be moved to. This is a required parameter.
  • The 
    overwrite
     (boolean) value is true if the existing file at targetPath can be over written. This is an optional parameter. By default, this value is false. 
  • The 
    keepOriginal
     (boolean) value is true if the file is copied to the targetPath and false if the file is to move to the targetPath. This is an optional parameter. By default, this value is false
Move Folder
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
foldername-with-path
}?action=move
POST
This function moves a folder to a new location.
The required request body is JSON, as shown in the following example: 
{
 "targetPath":"target-path",
 "overwrite":"true" Or "false",
 "keepOriginal":"true" Or "false"
}
  • The 
    targetPath
     (string) value is the path relative to repository path where the folder needs to moved to. This is a required parameter.
  • The 
    overwrite
     (boolean) value is true if the existing folder at targetPath can be over written. This is an optional parameter. By default, this value is false. 
  • The 
    keepOriginal
     (boolean) value is true if the folder is copied to the targetPath and false if folder is moved to the targetPath. This is an optional parameter. By default, this value is false.
Protect document
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with-path
}?action=protect
POST
This function protects a document. 
The required request body is JSON, as shown in the following example: 
{
 "templateId":"templateID",
 "expiryDate":"expiryDate"
}
  • The 
    templateID
     (string) value is the template ID required to protect the document. This is a required parameter. 
  • The 
    expiryDate
     (date) value is the date when protection expires. This is a required parameter and you must provide the date and time with the standard time zone or time offset. Use one of the following formats,
    • "2020:02:25T10:25:00.000-05:00", where 05:00 is the time offset
    • "2020-02-25T10:25:00.000Z", where Z is UTC time 
Unprotect document
http(s)://{
FQDN of the BEMS-Docs server
}:8443/docs/{
version
}/{
repository
}/{
filename-with-path
}?action=unprotect
POST
This function unprotects a document in the repository.
* Required for documents in flat view and Shared With Me 
Microsoft SharePoint
 libraries and specifies the actual path of document
** Required for Shared With Me 
SharePoint
 folders and specifies the actual path of the folder