Fundamentals

Client-Server Model

API execution follows Client-Server Model

• The Client makes the request to the BDRSuite over the HTTP protocol
• After receiving the request, request is formulated as per the operation to be performed as response

Response is provided in the form of status and message, representing either success or  failure or error message

HTTP Request and Response

POST creates an object to post a request using HTTP protocol to the Server and Server validates the request containing the parameters along with the Signature appended to the request provides the appropriate response.

Common Query Params

Every BDRSuite Backup Server API request will have to pass set of common parameters, listed in the below table.

NAME	DESCRIPTION
Action	The action to perform. Example: LIST_BACKUPS
Username	Login User name created for BDRSuite Backup Server web console
Signature 1	The request Signature1 created using HmacSHA256. Signature Method: The hash algorithm you use to create the request signature ( HmacSHA256.)
Signature Version	The signature version used to sign the request. Set this value to 2
Login Time	Time at which request being made and generated based on GMT and rendered in ‘Unix’ format.

Pseudo for Authparam

{“UserName”:”<APPLICATION_USER_NAME>”,”Signature1”:”<SIGNATUE_VALUE>”,”SignatureVersion”:2,”LoginTime”:”<UNIX_TIME>”}

Sample Authparam

{“UserName”:”admin”,”Signature1”:”6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec”,”SignatureVersion”:2,”LoginTime”:”1497704250”}

Sample HTTP API request

For LIST_BACKUPS API request with the above authparam, the complete API request will looks like below.

Note: BDRSuite Backup Server API request should only be in JSON format.

Endpoint URL

http://192.168.125.233:6060/bdrwebservices.php

Post Data

{“Action”:”LIST_BACKUPS”,”UserName”:”admin”,”Signature1″:”6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec”,”SignatureVersion”:2,”LoginTime”:”1497704250″}

Signing BDRSuite Webservices API request with signature

This section describes how to create signature and add it to a BDRSuite Webservices API request.

Below example illustrates, how an API request might looks like:

http://<IPAddress/Hostname>:6060/bdrwebservices.php

{“Action”:”LIST_BACKUPS”,”UserName”:”admin”,”Signature1”:”6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec”,”SignatureVersion”:2,”LoginTime”:”1497704250”}

Summary of Signing Steps

To create a signed request, complete the following;

Task 1 : Create a API request

Task 2 : Create a Secret Key

Task 3 : Create a signature for the API request

Task 4 : Add the signature information to the API request

Create a API request

Create API request in a standardized format, this ensure that when BDRSuite Backup Server receives API request, it calculate the same signature that you have calculated.

Follow the steps here to create API request, otherwise request calculated by you and request created by BDRSuite Backup Server won’t get matched and request will get denied.

API standardized format

API request =

HTTPRequestMethod

APIURI

QueryString

Signature

Example API request

API request =

Post

http://192.168.100.235:6060/bdrwebservices.php

{“UserName”:”admin”,”Signature1″:”6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec”,”SignatureVersion”:2,”LoginTime”:”1497704250″,”Action”:”LIST_BACKUPS”}

Start with the HTTP request method, (GET, PUT, POST, etc.)

BDRSuite Backup Server uses POST request method for all API calls and the POST data should be in JSON format.

The Endpoint URL structure for the requests to be made is as follows:

http://machine_name(or)machine_ip:port/bdrwebservices.php

Query String Parameters

Pseudocode for deriving a Secretkey

To create the secretkey,  concatenate algorithm and login time as shown in the following format.

Secretkey=

algorithm+login time

Following example shows how to construct secretkey;

1. Start’s with algorithm, This value is the hashing algorithm that we used to calculate the md5 of BDRSuite Backup Server application password,

For password admin : md5(admin)=21232f297a57a5a743894a0e4a801fc3

2. The login time value is calculated from the GMT Time Value and is rendered as, ‘Unix’ number.

1497704250

3.  Append algorithm value with login time value to create Secretkey.

21232f297a57a5a743894a0e4a801fc31497704250

Create the signature for the API request

Signature is the process of adding authentication information to BDRSuite Webservices API request.

Before you calculate the signature, make sure you have created secret key specified at step 2, deriving secret key is specific to the login time which will add extra protection to the API request.

Pseudocode for deriving a signature

Signature =

hmac_sha256(“<Secretkey>”, “<ActionName>”)

The following example shows the resulting signature if you use the same secret key and action name LIST_BACKUPS followed in this document.

6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec

Following examples shows a finished API request.

http://192.168.100.235:6060/bdrwebservices.php {“UserName”:”admin”,”Signature1″:”6cd32224ed0ac070f34121b70830b97b6d3ca55181508c8e95b0f9e78f84bfec”,”SignatureVersion”:2,”LoginTime”:”1497704250″,”Action”:”LIST_BACKUPS”}

How Signature works?

1. Create an API request.
2. You can use your application password along with login time to derive your signkey(Secret Key).
3. You can use your API action name and signkey(secretkey) to create a signature.
4. You can add this signature to API request in header or query string parameter.

When BDRSuite Backup server receives any API request, it will applies the same algorithm which you have used to generate the signature, if the signature matches then request will get processed otherwise request will get denied.