API Documentation

API Documentation

(Supported in version 10 and above)

CloudBasic’s REST API features a comprehensive list of API commands facilitating automated management of all aspects of the replication service from Amazon Lambda/CloudFormation or any DevOps tool.

This resource describes all REST API commands, corresponding data structures, as well as possible error codes. All API methods accept XML and JSON. API Response is rendered in XML or JSON accordingly. 


Default API Configuration

Default port

By default, the CloudBasic API is installed and configured to run on HTTP port 82. For HTTPS access on port 445 you need to RDP to the CloudBasic EC2 (Windows) instance and install SSL certificate (similarly to installing SSL certificate for Cluster communication on port 4431/444).

Ensure ports 82 and/or 445 are open and configured in the firewall (incl. in the CloudBasic EC2 Windows firewall) to allow HTTP and/or HTTPS communications.

 

API Security

Every interaction with the CloudBasic API must be authenticated. When making REST API calls you have to sign them using an Authorization Header with a signature created using valid credentials. To calculate the signature please follow the well accepted and thoroughly documented AWS Signature Version 4 signing process

A well-constructed sample Authorization Header would look like this:

Authorization: AWS4-HMAC-SHA256 
Credential=DJHDYSIRYGJBEETGDQCP/20170905/us-east-1/cbr/aws4_request, 
SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date, 
Signature=865c09d640daf17eaed637d25360d132e8a815da39deb1b94b38638a04875f7b

At a very high level the AWS Signature Version 4 process includes the following four steps:

1. Create a canonical request
2. Use the canonical request along with additional information to create a string to sign
3. Use your CloudBasic secret access key to derive a signing key, and then use that signing key and the string to create a signature
4. Add the resulting signature to the HTTP request’s header

Please see the following link for a sample c# implementation.

Management of Key pairs

The AWS Signature Version 4 signing process requires the usage of an Access Key ID and a Secret Access Key. CloudBasic supports two ways to manage your Access Keys:

Initial Key retrieval for new users

When a new user is created using the CloudBasic API, a new pair of Access Key ID and Secret Access Key are generated and return in the response. Please note that, for security reasons, there is no way to replace the Access Key ID and Secret Access Key generated using the CloudBasic API. This can be done only using the CloudBasic console.

Key management using the CloudBasic console

Access Key IDs and Secret Access Keys can be managed for any user using the CloudBasic console. Please note that the Secret Access Key can be displayed only once when a new Key pair is created.

To create a new Key Pair:
1. Select the user
2. Click "Create access key"
3. Click "Show"
4. Copy the Secret Access Key and store in a secure location

 

Common Request Headers

Header Name Description
X-Amz-Content-Sha256 When using signature version 4 to authenticate request, this header provides a hash of the request payload. Please see the section API Security for more information.
Content-Type The content type of the resource. For example: application/x-www-form-urlencoded
X-Amz-Date The current date and time
Authorization Contains the information required for request authentication. Please see the section API Security for more information.
 
 

Common Response Headers

 
Header Name Description
X-Amz-Content-Sha256 When using signature version 4 to authenticate request, this header provides a hash of the request payload. Please see the section API Security for more information.
Content-Type The content type of the resource. For example: application/x-www-form-urlencoded
X-Amz-Date The current date and time
Authorization Contains the information required for request authentication. Please see the section API Security for more information.
 

REST Error Responses

When an error is encountered, the header information will contain:
- content-type: application/xml; charset=utf-8
- an appropriate 4xx HTTP status code.

The body of the response will contain information about the specific error that occurred.

Sample Error Response Syntax – using XML parameter encoding

HTTP/1.1 400
status: 400

<?xml version="1.0" encoding="utf-8"?>
<Error>
 <RequestId>request-id</RequestId>
 <Message>error-specific-message-text</Message>
</Error>

Error Response Parameters

Parameter Description
RequestID Numeric value that uniquely identifies the API request. This can be helpful when troubleshooting CloudBasic API issues.
Error String value that provides a description of the encountered problem

Passing Parameters

The CloudBasic API accepts parameters in the Body of the request and recognizes either an XML or JSON formatting.

 

API Actions

Instance Management

User Management

Replication Management

Multi-AZ HA Cluster Management

Lambda/node.js Example

 

Top of page