API

AhsayCBS contains a set of APIs (Application Programming Interface), which allows you to integrate your own or external applications (e.g. billing system or automated registration system) with AhsayCBS.

AhsayCBS comes with a set of REST APIs which is JSON (JavaScript Object Notation) based JavaScript syntax. It can be read and used as a data format by any programming language (Java, Python, PHP, C cURL, etc.) to develop your own custom application or reporting tool.

API request can be invoked by using POST method only.

All examples as shown for the discussed APIs in future chapters are all based on the latest API versions (v2).

Here is a sample of the JSON request input:

{
     "SysUser":"APluser",
     "SysPwd":"my_password",
     "Hostname":"mybackup.com",
     ...
     :
     :
     :
}

For further reference on the JSON syntax or documentation, please refer to:

JSON - Introduction

What is JSON?

More examples are available in the following API sections

Limitations and Recommendations

For backwards compatibility, AhsayCBS version 9 supports the use of some APIs from legacy version 6 (API in XML format). However, your results may vary, and it is recommended for programmers to change all existing legacy coding with the use of the JSON syntax API in relation to the support of new features in version 9.

New features introduced in AhsayCBS version 9 will not be supported by APIs written and based on Ahsay version 6 XML formatting. Continued use of the XML API may yield unexpected results.

If you run multiple AhsayCBS servers with varying AhsayCBS versions (i.e. CBS v7.17, v8.5, and v9.1 in your environment), when developing your own application that calls Ahsay API requests, we suggest you use API to check the AhsayCBS version, then call the corresponding API request for that AhsayCBS version.

With some API methods, there may be two versions: “v1” and “v2”. For features related to Quota Management, v2 was produced to handle these features initially introduced in AhsayCBS v7.15.6.38. If your AhsayCBS is higher than this version, you should already be using v2 API. If your application is requesting data from AhsayCBS v7.15.6.38 or earlier, then continue to use v1 API.

There may be other enhancements which have deprecated other API, for example “GetLicense.do” in AhsayCBS v8.3.

Additional details for limitations and recommendations include:

Coding for your application must support UTF-8.
When testing your API, ensure that you have all parameters and/or settings setup on your AhsayCBS.
Please arrange your test casein a logical sequent, such as creating a backup set before attempting to Modify / Delete a backup set with API.

This Ahsay v9 API Guide has removed the "v1" API methods deprecated by v7.15.6.38. For details regarding "v1" API, please request older API Guide(s) from Ahsay Support.

API Access Account Types

To allow a third-party program to utilize the API, it is suggested that you create a "System User" which has permission for API calls to your AhsayCBS.

For all APIs outlined in this guide with parameters, "SysUser" and "SysPwd", they are the username and password of any or the following types of "System User":
- Admin
- API User
For some APIs, as listed in the following sections in this guide, API with parameters "SysUser" and "SysPwd", are the username and password of the following type of "System User":
- Read-Only API User

Sub-Admin account types are not permitted to make any API request.

Read-Only API User

AhsayCBS version 9 introduces the “Read-Only API User” account type. This allows your application to access Read-Only data and not allow changes to be made if this account were to be compromised.

Valid Read-Only API User API Methods

System API

API	API Methods
System	GetBuildingStatus
	GetReplicationStatus
	GetSystemStatus
	GetDataMigrationProgress
System Config	GetLicense (v1, v2)
	GetReplicationMode
	GetSystemSetting (v1, v2) - Backup Server
Group Policy	ListPolicyGroups (v1, v2)
Group Policy	ListUserGroups

User API

API	API Methods
User	ListUsers (v1, v2)
	GetUser (v1, v2)
	GetSingleUserRebuildStatus
	GetUserStatus
	GetUserStorageStat
	GetServerRunJobStatus
Backup Set	GetBackupJobProgress
	GetBackupSet (v1, v2)
	ListBackupFiles
	ListBackupJobMode
	ListBackupJobs
	ListBackupJobsStatus
	ListBackupSets
	ListRestoreJobs
	ListRestoreJobStatus
Report	GetBackupJobReport
	GetBackupJobReportSummary
	GetRestoreJobReport

RPS API
API API Methods
RPS Receiver ListReceiver

API	API Methods
RPS Receiver	ListReceiver

For more information on each API and API Method, you may jump ahead to sections System API, User API and RPS API respectively.

2FA One-time Passcode Parameter

Beginning with version 9.7, if a System User has Two-Factor Authentication enabled, or if making use of an API that makes use of Immutable Destinations, a special Parameter will be needed to authenticate each API call that a user makes.

Parameter	Description
OnetimePasscode	One-time passcode generated from an authenticator app. Required if 2FA is enabled for SysUser or if destination to be added is immutable.

The one-time passcode to be used for the Parameter is the same passcode as shown on the registered authenticator app. As these codes expire and change every few seconds, the code input in the “OnetimePasscode” parameter also changes.

To make use of this special parameter, see API call sample below:

INPUT for GetBuildingStatus.do?product=CBS

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"OnetimePasscode":"887707"
}

OUTPUT

{
	"Status":"OK",
	"lastUpdatedTime":"2024-05-05 7:40:57",
	"message":"",
	"status":"waiting"
}

IP Restrictions

By default, AhsayCBS accepts and handles API requests from all IP addresses. To avoid being exploited by hackers from an unauthorized network, you will need to setup IP filters.

Setup IP filters with the following:

Stop the AhsayCBS service.
Open the web.xml file in the following paths:
- %CBS_HOME%\webapps\cbs\WEB-INF\web.xml
- %CBS_HOME%\webapps\rps\WEB-INF\web.xml
- %CBS_HOME%\webapps\rdr\WEB-INF\web.xml
- %CBS_HOME%\webapps\obs\WEB-INF\web.xml
%CBS_HOME%\webapps\obs\WEB-INF\web.xml ("/obs/apit/json/" API)
- Cannot be fully restricted because it is used by the AhsayOBM and AhsayACB Client agent
- Can have restrictions if you include the range for all your user's IP subnets.
Locate the "ApiAccess" filter under the "filter" section.

Change the "Range2" (<param-name>Range2</param-name>) parameter value from "0.0.0.0-255.255.255.255" to another range of IP addresses from where APIs can be invoked.

<filter>
	<filter-name>ApiAccess</filter-name>
	<filter-class>com.ahsay.obs.www.IPFilter</filter-class>
	<init-param>
		<param-name>Range1</param-name>
		<param-value>localhost</param-value>
	</init-param>
	<init-param>
		<param-name>Range2</param-name>
		<param-value>0.0.0.0-255.255.255.255</param-value>
	</init-param>
</filter>

For example, change the [Range2] valuefrom "0.0.0.0-255.255.255.255" to "192.168.1.1-192.168.1.255" to allow the 192.168.1.x network to invoke APIs.

<filter>
	<filter-name>ApiAccess</filter-name>
	<filter-class>com.ahsay.obs.www.IPFilter</filter-class>
	<init-param>
		<param-name>Range1</param-name>
		<param-value>localhost</param-value>
	</init-param>
	<init-param>
		<param-name>Range2</param-name>
		<param-value>192.168.1.1-192.168.1.255</param-value>
	</init-param>
</filter>

Please note that you can configure more than two IP ranges by adding additional init parameters (i.e. "Range3", "Range4", and so on) to the filter SML tag. For example:

<filter>
	<filter-name>ApiAccess</filter-name>
	<filter-class>com.ahsay.obs.www.IPFilter</filter-class>
	<init-param>
		<param-name>Range1</param-name>
		<param-value>localhost</param-value>
	</init-param>
	<init-param>
		<param-name>Range2</param-name>
		<param-value>192.168.1.1-192.168.1.255</param-value>
	</init-param>
	<init-param>
		<param-name>Range3</param-name>
		<param-value>192.168.2.1-192.168.2.255</param-value>
	</init-param>
</filter>

Restart the AhsayCBS service.

Troubleshooting

Here are some common mistakes when people write their own JSON scripts.

Erroneous Characters (Trailing Spaces)

Reason for the error below is the trailing space following "GetLicense.do "

"https://CBS.EXAMPLE.COM/obs/api/json/2/GetLicense.do "

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
}

OUTPUT

404 NOT FOUND
No body returned for response

Syntax Errors

Sample 1

GetLicense.do API Input - Missing comma and/or double quote

{
	"SysUser":"api_user",
	"SysPwd":qWeRtY123456!@#$%",
}

OUTPUT

{
	"Status":"Error",
	"Message":"[Error] JSON Input Syntax is incorrect!",
	"ExptType":"java.lang.Exception"
}

Missing the above syntax would cause critical errors.

Correct input

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
}

OUTPUT

{
	"Status":"OK",
}

Sample 2

UpdateConfig.do API Input - Array missing square brackets "[ ]"

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"SendBccReports":true,
	"AdminContact":{"Name":"New1","Email":New1@example.com}
}

OUTPUT

{
	"Status":"Error",
	"Message":"Invalid input type, JSONObject[\”AdminContacts\”] is not a JSONArray (class org.json.JSONObject).",
	"ExptType":"org.json.JSONException"
}

The input data type for AdminContacts is an array. Arrays must be set in square brackets "[ ]".

Correct input

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"SendBccReports":true,
	"AdminContact":[{"Name":"New1","Email":New1@example.com}]
}

OUTPUT

{
	"Status":"OK",
}

Parameter Name Typo Errors

GetLicense.do API Input - Incorrect parameter name

{
	"SySUser":"api_user",
	"SySPwd":"qWeRtY123456!@#$%",
}

OUTPUT

{
	"Status":"Error",
	"Message":"[Error] Parameter SysUser is null!",
	"ExptType":"java.io.IOException"
}

Parameter names are case sensitive. Ensure that all parameter names are in the correct case, as outlined in this document.

Correct input

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
}

OUTPUT

{
	"Status":"OK",
}

Extra Key Inputs

UpdateUser.do API Input - Erroneous Key "foobar" is ignored

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"LoginName":"backup_user",
	"foobar":"foobar_is_extra_and_irrelevant"
}

OUTPUT

{
	"Status":"OK"
}

Input of extra key(s) are ignored by AhsayCBS, is not validated, and will not display an error code.

Escape Character Errors

AddSelectSrc.do API Input - Character Backslash (\) not escaped (\\)

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"LoginName":"opendirect",
	"BackupSetID":"1497925931498",
	"NewSelectedSrc":{"Src":"C:\SelectSrcTestOBM"}
}

OUTPUT

{
	"Status":"Error",
	"Message":"[Error] JSON Input Syntax is incorrect!",
	"ExptType":"java.lang.Exception"
}

Make sure your values are specific for JAVA characters (e.g. "\\" for escape)

AddSelectSrc.do API Input - Character Backslash (\) not escaped (\\)

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"LoginName":"opendirect",
	"BackupSetID":"1497925931498",
	"NewSelectedSrc":{"Src":"C:\\SelectSrcTestOBM"}
}

OUTPUT

{
	"Status":"OK"
}

Incorrect API URL Path

Incorrect https://CBS.EXAMPLE.COM/obs/api/json/UpdateConfig.do

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
}

OUTPUT

No body returned for response

Make sure you point to the correct API URL path. For "UpdateConfig.do", it is under /cbs/api.

Correct https://CBS.EXAMPLE.COM/cbs/api/json/UpdateConfig.do

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
}

OUTPUT

{
	"Status":"OK"
}

If the error message returned by the API call does not provide sufficient information, please login to the AhsayCBS console for further details: Dashboard > To Dos > API Errors.

API Errors

You can contact the Ahsay support team for further assistance.

Proceed to the specific section of the following APIs:

API

Limitations and Recommendations

API Access Account Types

Read-Only API User

2FA One-time Passcode Parameter

To make use of this special parameter, see API call sample below:

IP Restrictions

Troubleshooting

Erroneous Characters (Trailing Spaces)

Syntax Errors

Sample 1

Sample 2

Parameter Name Typo Errors

Extra Key Inputs

Escape Character Errors

Incorrect API URL Path

Company