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
The Communication with BDRSuite is established through HTTP protocol in the form of request using POST method and Response is received.
Requests 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;
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 |
---|
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 |
---|
After you calculate the signature, final thing you need to do is adding it to HTTP header named “Signature”
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?
Create an API request.
You can use your application password along with login time to derive your signkey(Secret Key).
You can use your API action name and signkey(secretkey) to create a signature.
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.