RAID Management

The VAPIX® RAID Management API provides the information that makes it possible to set up and monitor the status of a RAID (Redundant Array of Independent Disks), which is a combination of multiple devices exposed as a single logical device on a system. This allows you to distribute a load of data over multiple components while addressing them as if they were one storage device.

Different characteristics and features can be achieved depending on selected RAID levels, such as device failure redundancy and performance improvements. This means that either one or both benefits can be attained to various extents depending on RAID level and the number of available component devices.

Examples of RAID levels

RAID levels 1, 5, 6 and 10 provide device failure redundancy. This means that one or more components can be lost during a configuration while the data remains intact. RAID levels that can give some disks I/O performance are 0, 5 and 10.

The currently supported RAID levels are raid0, radi1, raid5, raid6 and raid10.

Terminology

Term	Description
RAID	Redundant Array of Independent Disks
RAIDs	Plural of RAID. Redundant Array of Independent Disks
RAID-level	A selected behavior of a RAID.
storage device	Stores bits of data.
hard disk drive	An example of a type of storage device.
partition	The logical arrangement of physical storage space accessible by the operating system.
component device	A storage device/partition that participates in a RAID.
component	Short name for component device.
sync	The process of calculating information used to provide component device failure redundancy.
degraded	Whenever a RAID is in a degraded state it is still active, but has lost its data redundancy.
connected	A component available for use or in active use in a RAID.
missing	A component that was used in RAID that isn’t connected.
spare	A connected component that is in standby for immediate replacement when needed.
API	Application Programming Interface.
HTTP	Hyper Text Transfer Protocol, a commonly used protocol for communicating over the internet.
JSON	Java Style Object Notification, a standardized way of serializing data.

Overview

The API implements disks/raid.cgi as its communications interface and supports the following methods:

getStatus: Check the RAID state and its component devices to see which components are connected or missing. Additional information such as serial numbers are also available with this method.
Please note that component devices are not the same as the disks referenced in the Disk management API. This means the components won’t be listed using disks/list.cgi. The RAID itself is a disk, and can be used as such once it is formatted using format.cgi. Since the RAID can only provide failure redundancy for components once it has synced, a component can be lost while the RAID disk still has the status OK in disks/list.cgi. To get the connection status of the components this method must be used instead of list.cgi.
getCapabilities: Check for supported RAID levels. Possible RAID levels are raid0, radi1, raid5, raid6 and raid10.
recreateRaidOnAllComponents: Set up a RAID on all available components.
Please make sure that all important data in the active RAID is backed up before using this method as using this method while RAID is active will stop, destroy and replace the active RAID and create a new one.
The reasons you would want to recreate the RAID with this method is to either change the RAID level from the default value, or to setup a new RAID on fewer or on an entirely new set of component devices. The latter option is viable when multiple hard disk drives breaks down before you are able to sync a replacement drive, however please note that this scenario unfortunately will result in data loss.
Provided that an expected number of components are available a RAID is automatically configured at the first time setup. This method can be used to create a RAID on fewer components than the usual amount as long as the selected RAID level is supported for that number of components.
Attempting to configure a RAID level that is not supported will reply with the error code 1201 “RAID level not supported”. The getCapabilities method should be used to check supported RAID levels.
Successful implementation creates a logical device in a syncing state which can be used immediately. The device still needs to be formatted with a file system and then mounted to be used in the system.
getSupportedVersions: Discover all API versions supported by your device.

Identification

API Discovery: id=raid

Common examples

Check RAID status

Use this example to check if all connected hard drives are in a state expected by the system.

1. Retrieve the current status of your hard drives and sync progress with the following request:

POST http://<device-adress>/axis-cgi/disks/raid.cgi
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getStatus"
}

2. Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getStatus",
  "data": {
    "raids": [
      {
        "status": "degraded",
        "syncProgress": 0,
        "syncTimeRemaining": 0,
        "raidLevel": "raid5",
        "components": [
          {
            "componentStatus": "connected",
            "componentId": "0",
            "serialNumber": "ABC123",
            "capacity": 1234
          },
          {
            "componentStatus": "missing",
            "componentId": "1",
            "serialNumber": "unknown",
            "capacity": 0
          },
          {
            "componentStatus": "connected",
            "componentId": "2",
            "serialNumber": "CAB312",
            "capacity": 1234
          }
        ]
      }
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getStatus",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

See getStatus for additional information.

Retrieve capabilities

Use this example to locate and retrieve available RAID levels.

1. Retrieve available RAID levels with the following request:

POST http://<device-adress>/axis-cgi/disks/raid.cgi
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities"
}

2. Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities",
  "data": {
    "raidLevels": [
      "raid0", "raid1", "raid5", "raid6", "raid10"
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

See getCapabilities for additional information.

Change RAID level

Use this example to chose the RAID level that you want to use in the system.

Note

Changing from one RAID level to another is an irreversible operation that will destroy all data in the active RAID, resulting in permanent loss of data.

1. A new RAID can be created using the recreateRaidOnAllComponents method if a RAID level other than the default “raid5” is preferred. Please note that the RAID must first be unmounted using disks/mount.cgi from Edge storage API before you replace an existing and actively used RAID.

2. Making a request to disks/raid.cgi with the getCapabilities method selected must be made in order to present and select available RAID levels. This will return a list containing RAID levels available for selection.

3. The following example uses the method recreateRaidOnAllComponents and the level “raid10”:

POST http://<device-adress>/axis-cgi/disks/raid.cgi
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "recreateRaidOnAllComponents",
  "params": {
    "raidLevel": "raid10"
  }
}

4. Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "recreateRaidOnAllComponents",
  "data" {}
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "recreateRaidOnAllComponents",
  "error": {
    "code": 1201,
    "message": "RAID level not supported"
  }
}

5. The method getStatus can be used to verify that a new RAID is created with level “raid10” and is properly syncing.

Note

Please note that a RAID is created without a file system. However, disks/format.cgi, further detailed in Edge storage API can be used to format a file system.

6. A file system can be mounted once it has been properly created with mount.cgi and the action mount , detailed in Edge storage API.

See recreateRaidOnAllComponents for additional information.

Get supported versions

Use this example to retrieve a list containing the API versions supported by your device.

1. Retrieve supported API versions with the following request:

POST http://<device-adress>/axis-cgi/disks/raid.cgi
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "context": "123",
  "method": "getSupportedVersions"
}

2. Parse the JSON response.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions",
  "data": {
    [
      "1.0"
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

See getSupportedVersions for additional information.

API specifications

getStatus

This method is used when you want to retrieve the current status of configured RAIDs.

Request

Security level: Operator
Method: HTTP POST

http://<device-address>/axis-cgi/disks/raid.cgi

Request body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getStatus"
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that should be used.
`context=<string>`	The context set by the user and echoed in the response (optional).
`method="getStatus"`	The requested method.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getStatus",
  "data": {
    "raids": [
      {
        "status": <string>,
        "syncProgress": <integer>,
        "syncTimeRemaining": <integer>,
        "raidLevel": <string>,
        "components": [
          {
            "componentStatus": <string>,
            "componentId": <string>,
            "serialNumber": <string>,
            "capacity": <integer>
          },
          {
            "componentStatus": <string>,
            "componentId": <string>,
            "serialNumber": <string>,
            "capacity": <integer>
          }
        ]
      },
      {
        "status": <string>,
        "syncProgress": <integer>,
        "syncTimeRemaining": <integer>,
        "raidLevel": <string>,
        "components": [
          {
            "componentStatus": <string>,
            "componentId": <string>,
            "serialNumber": <string>,
            "capacity": <integer>
          },
          {
            "componentStatus": <string>,
            "componentId": <string>,
            "serialNumber": <string>,
            "capacity": <integer>
          }
        ]
      }
    ]
  }
}

Parameter Description

apiVersion=<major>.<minor> The API version that was used in the request.

context=<string> The context set by the user in the request (optional).

method="getStatus" The method that was requested.

data.raids=[<object>] A list of RAIDs.

data.raids.<object>.status=<string>

The momentary RAID status. The following table contain the values of the status parameter:

Value	Description
`active`	The RAID is operating with optimal performance.
`degraded`	The RAID is missing data redundancy.
`syncing`	The RAID is synchronizing data between components.
`failure`	The RAID has failed.

data.raids.<object>.syncProgress=<integer> The percentage of completion during an active sync process. Set to 100 when active and not syncing and 0 when in a degraded or failed state.

data.raids.<object>.syncTimeRemaining=<integer> The estimated time, in seconds, until an active sync finishes. Set to 0 when not syncing.

data.raids.<object>.raidLevel=<string> Returns the configured RAID level. Use the method getCapabilities to list supported RAID levels.

data.raids.<object>.components=[<object>] Lists the component device information.

data.raids.<object>.components.<object>.componentId=<string> The component device ID. Maps to a hard drive slot on your product.

data.raids.<object>.components.<object>.componentStatus=<string>

Status of the component device. The following table contain the values of the componentStatus parameter:

Value	Description
`connected`	The component device is available in the active RAID.
`missing`	The component device is not detected.
`spare`	The component device is marked as a hot-spare.

data.raids.<object>.components.<object>.serialNumber=<string> The serial number of the component device.

data.raids.<object>.components.<object>.capacity=<integer> The capacity, in gigabytes, of the component device.

Return value - Error

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getStatus",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="getStatus"`	The method that was requested.
`error=<object>`	The error object.
`error.code=<integer>`	An error code describing the kind of error.
`error.message=<string>`	An error message describing the error code.

Error codes

See General error codes for a complete list of potential errors.

getCapabilities

This method is used when you want to retrieve product supported RAID-levels. It will be presented as a subset of the list of possible RAID levels. Possible RAID levels are raid0, radi1, raid5, raid6 and raid10.

Request

Security level: Operator
Method: HTTP POST

http://<device-address>/axis-cgi/disks/raid.cgi

Request body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getCapabilities"
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that should be used.
`context=<string>`	The context set by the user and echoed in the response (optional).
`method="getCapabilities"`	The requested method.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getCapabilities",
  "data": {
    "raidLevels": [
      <string>,
      <string>
    ]
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="getCapabilities"`	The method that was requested.
`data.raidLevels=[<string>]`	The list of available RAID levels.

Return value - Error

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getCapabilities",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="getCapabilities"`	The method that was requested.
`error=<object>`	The error object.
`error.code=<integer>`	An error code describing the kind of error.
`error.message=<string>`	An error message describing the error code.

Error codes

See General error codes for a complete list of potential errors.

recreateRaidOnAllComponents

This method is used when you want to setup a RAID.

Request

Security level: Admin
Method: HTTP POST

http://<device-address>/axis-cgi/disks/raid.cgi

Request body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "recreateRaidOnAllComponents"
  "params": {
    "raidLevel": <string>
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that should be used.
`context=<string>`	The context set by the user and echoed in the response (optional).
`method="recreateRaidOnAllComponents"`	The requested method.
`params.raidLevel=<string>`	The RAID-level.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "recreateRaidOnAllComponents",
  "data": {}
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="recreateRaidOnAllComponents"`	The method that was requested.

Return value - Error

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "recreateRaidOnAllComponents",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="recreateRaidOnAllComponents"`	The method that was requested.
`error=<object>`	The error object.
`error.code=<integer>`	An error code describing the kind of error.
`error.message=<string>`	An error message describing the error code.

Error codes

Code	Message
`1200`	Generic RAID error.
`1201`	RAID level not supported.
`1202`	Component device error.

See General error codes for a complete list of potential errors.

getSupportedVersions

This method is used when you want to retrieve a list of API versions supported by your device.

Request

Security level: Operator
Method: HTTP POST

http://<device-address>/axis-cgi/disks/raid.cgi

Request body syntax

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Parameter	Description
`context=<string>`	The context set by the user and echoed in the response (optional).
`method="getSupportedVersions"`	The requested method.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      "<major1>.<minor1>", "<major2>.<minor2>"
    ]
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="getSupportedVersions"`	The method that was requested.
`data.apiVersions=[<object>]`	A list containing the major API versions along with their supported minor version, e.g. [`“1.3”, “2.1”`].

Return value - Error

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<major>.<minor>`	The API version that was used in the request.
`context=<string>`	The context set by the user in the request (optional).
`method="getSupportedVersions"`	The method that was requested.
`error=<object>`	The error object.
`error.code=<integer>`	An error code describing the kind of error.
`error.message=<string>`	An error message describing the error code.

Error codes

See General error codes for a complete list of potential errors.

General error codes

API specific error codes
Code	Message
`1200`	Generic RAID error.
`1201`	RAID level not supported.
`1202`	Component device error.

Generic error codes
Code	Message
`1100`	Internal error.
`2101`	Invalid JSON
`2102`	Method not supported.
`2103`	Required parameter missing.
`2104`	Invalid parameter value specified.
`2105`	Authorization failed.
`2106`	Authentication failed.
`2107`	Transport level error.