1193 - How to use the Storage Platform REST API

Note: This article applies to the Storage Platform API and not the RedAPI. You can find our RedApp API documentation here.

Introduction

The Storage Platform can be administered with the use of a RESTful API. This article outlines the various endpoints, the sequence of calls (operations) and their arguments.

• Functionality on the Storage Platform is restricted and access is authenticated using basic HTTP over SSL. All API access requires the user to authenticate.
• Only a Collection Administrator can perform administrative functions. The exception is the creation of Storage Pools, which can only be done by a top-level Platform Administrator. This can be the same user as for the Console.
• StorageServer API endpoints are not accessible to access users unless they have Storage Pool Administrator or top-level access rights.
• Communications are directed to the Redstor AccountServers, which collect event data from the StorageServers, including those which are self-hosted.
• API integration directly to StorageServers is not supported.
• REST calls can also be made with other programming languages, such as Python.
• Data is presented in bytes, not bits.

The API

Note: This guidance applies to customers who use self-hosted StorageServers attached to the Redstor platform. Customers on self-hosted Storage Platforms will need to change the addresses to those in their environment.

The primary endpoints to use are:

• ZA: https://zaapi.pro.redstor.com
• UK & rest of world: https://api.pro.redstor.com

API calls will be based on the following base URL:

• https://<AccountServer>/api/docs/v1
• https://<StorageServer:Port>/api/docs/v1

You can access an interactive user-interface of the documentation for all endpoints here:

• https://<AccountServer>/api/swagger/index#/
• https://<StorageServer:Port>/api/swagger/index#/

See the diagram below for notes on the user interface:

Guides

How to use Windows Powershell to call the API

GET

function Get-Groups{param($ASIP,$ASPort,$Username,$Password)
$uri = "https://$ASIP" + ":" + "$ASPort/api/backup/Groups"
$authheader = "Basic " +
([Convert]::ToBase64String([System.Text.encoding]::ASCII.GetBytes($Username+":"+$password)))
$result = Invoke-RestMethod -Headers @{Authorization=$authheader} -Method get -uri $uri
Return $result
}

Function call example:

Get-Groups -ASIP api.pro.redstor.com -ASPort 443 -Username joe.blogg -Password password456!?

POST

function Create-Group{param($ASIP,$ASPort,$Username,$Password,$groupName)
$body = @"
{
"Name": "$groupName",
"GroupType": "BackupGroup",
"ParentId": 1,
"GroupKey": "password",
"MaxSizeGB": 400,
"DefaultLimitMB": 1,
"StoragePoolId": 1,
"SmallFileThreshold": 20480,
"NotifyType": "TelephoneAndEmail",
"Deleted": " false",
"NotificationEmailsSender": "tomorrow",
"NotifyMessage2": "tomorrow",
}
"@
$uri = "https://$ASIP" + ":" + "$ASPort/api/backup/Groups"
$authheader = "Basic " +
([Convert]::ToBase64String([System.Text.encoding]::ASCII.GetBytes($Username+":"+$password)))
Invoke-WebRequest -Headers @{Authorization=$authheader} -Method post -uri $uri -Body $body -
ContentType "application/json"
}

Function call example:

Create-Group -ASIP api.pro.redstor.com -ASPort 443 -Username joe.blogg -Password password456!? -groupName MyGroup

How to create a Collection

Request notes:

• • • Exclude "ParentId" in order to create a Collection in the topmost node of the Storage Platform tree available to your user.
    • "GroupType" must be set to "AdminGroup" for Collections.

Response notes:

• • • "id" contains the Collection ID of the newly created Collection.

How to create a Group

Request notes:

• • • "ParentId" must be the Collection/Group ID of the parent Collection/Group previously created.
    • "GroupType" must be set to "BackupGroup" for Collections.

Response notes:

• • • "id" contains the ID of the newly created Group.

How to allocate a licence

Request notes:

• • • Set "id" to that of the relevant Group (use the "id" returned from the /api/backup/groups call).
    • For "LicenceNr", 0 = DL, 1 = SE, 3 = ESE.
    • Several licence types can be allocated at once by adding more items to the array for different "LicenceNr" values.

Response notes:

• • • No response body is expected unless an error occurs.

How to create an Account

Note: You will need to reconnect to the ESE/SE/DL client to use the Account.

Request notes:

• • • "BackupGroupId" must be the Group ID of the parent Group.
    • For "TypeId", 0 = DL, 1 = SE, 3 = ESE.

Response notes:

• • • "id" contains the Account ID of the newly created Account.

How to retrieve Group IDs

Response notes:

• • • An array will be returned containing Groups and Collections.
    • Parents and children are included. Hierarchy is indicated by the "id" and "ParentId" fields.

How to change a Group's name

Request notes:

• • • "id" must be the Group ID of the Group be to updated (use the "id" returned from /api/backup/Groups).
    • Contains a JSON-formatted string with only the relevant field(s) to be updated.

Response notes:

• • • No response body is expected unless an error occurs.

How to retrieve a Group's Account information

The following URL includes OData query options to refine the information returned. All Accounts for a Group will be returned using the criteria below.

Request notes:

• • • "id" must be the Group ID of the Group whose Accounts are to be retrieved (use the "id" returned from /api/backup/Groups).

Response notes:

• • • An array will be returned containing all information for each Account in the Group.
    • Use the "BackupGroupId" to confirm hierarchy.

How to retrieve the Last Backup Date for a specific Account

Request notes:

• • • Set {id} to that of the the relevant Account. Use the "id” returned from calling /api/backup/Accounts?$filter=BackupGroupId%20eq%20{ID} (for a Group) or /api/backup/Accounts (for all Accounts on the Storage Platform).

Response notes:

• • • An array is returned containing the requested field "LastBackupDate".

How to change the size of a specific Account

Request notes:

• • • Set {id} to that of the relevant Account.
    • Contains a JSON-formatted string with the relevant field(s) to update.
    • "Limit" is shown in MB.

Response notes:

• • No response body is expected unless an error occurs.