Fundamentals

Fundamentals

Client-Server Model

API execution follows Client-Server Model
  1. The Client makes the request to the BDRShield over the HTTP protocol.
  2. 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 BDRShield 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 BDRShield Backup Server API request will have to pass set of common parameters, listed below.
NAME
DESCRIPTION
Action
The action to perform. Example: LIST_BACKUPS
Username
Login User name created for BDRShield 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.
Notes
Note: BDRShield 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 BDRShield Webservices API request with signature

This section describes how to create signature and add it to a BDRShield 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 BDRShield 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 BDRShield 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”}

  1. Start with the HTTP request method, (GET, PUT, POST, etc.)
  2. BDRShield 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 BDRShield 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 BDRShield 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
Add the signature information to the API request. 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?

  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 BDRShield 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.

    • Related Articles

    • Introduction

      BDRShield exposes its objects with WebServices Application Programming Interface(API) by invoking actions through HTTP protocol in the form of requests with the corresponding parameters and receiving responses for the action This topicwill help you ...