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.

Note: Paging and recursion cannot be specified in the same request if the format is specified as nested.

For an example of a list documents output, see File shares folder listing and metadata output and SharePoint folder listing and metadata output.

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