Using the Storage Advisor RESTful API
The Storage Advisor API is a REST (representational state transfer) interface for administrative tasks to manage storage resources.
Storage Advisor is a unified software management tool that reduces the complexity of managing storage systems by simplifying the setup, management, and maintenance of storage resources.
REST architecture
REST is a style of software architecture that can be used with many message formats for web services.
REST uses the HTTP protocol along with a uniform resource identifier (URI) to identify a name of a web resource for requests from the client.
Storage Advisor REST API provides a non-GUI interface to storage management operations. It supports JSON requests and responses only.
API functionality and HTTP methods
HTTP defines a set of methods that define the actions that can be performed on a resource.
The API supports the following HTTP methods:
Method | Description |
GET |
Retrieves information about an individual resource or retrieves a list of resources of a given type. GET is a synchronous operation. Synchronous operations return a response message with information for the given resource. All GET API calls support filtered queries. The GET jobs API has a searching and sorting structure: https://ipAddress/v1/jobs?q=query&sort=sorting (where everything after the "?" is optional). Here are a few examples:
|
POST |
Adds (creates) and updates a resource. You need to provide values for all of the attributes of a resource that do not have default values. To override a default value, include the attribute and provide an override value for that attribute in the request body. POST operations that are asynchronous, return a response message with information about the status and job of the request. POST operations on resources in Storage Advisor are asynchronous with the following exceptions. These operations are synchronous and the response that is returned is a response message with only a HTTP status code.
|
PATCH | The PATCH method applies partial modifications to a resource. |
DELETE |
Deletes a resource. DELETE operations that are asynchronous, return a response message with information about the status and job of the request. DELETE operations on resources in Storage Advisor are an asynchronous operation with the following exceptions. These operations are synchronous and the response that is returned is a response message with only a HTTP status code.
|
Privileges and roles
Access to the storage system is restricted by roles. Roles determine what a user can and cannot do. The security administrator can grant access to users by assigning users roles with privileges that are attached to those specific roles.
Roles | Privileges |
System administrator |
|
Storage administrator |
|
Security administrator |
|
Monitoring role | Read-only privileges to monitor everything in Storage Advisor. |
Identifying a resource
The REST API allows you to manage and configure resources on the storage system including common storage systems, disks, parity groups, pool, volumes, ports, and tiers.
To identify a resource you want to manage, enter a resource domain URL in a web browser. All URLs for Storage Advisor API have the following base or root, uniform resource identifier (URI):
https://management-server/v1
where:
management-server is the virtual IP address or resolvable management server name of Storage Advisor.
For example, you can use the following URI to display a list of servers and details for each server.
https://172.17.35.70/v1/compute/servers
Each resource (URI) can only be accessed by users with correct privileges. Privileges are inherited based on the roles that are assigned to users.
HTTP response
When an HTTP request is sent, the server sends back an HTTP response message. The HTTP response message consists of an HTTP header and optional message body. Within the response header is the HTTP status code. The HTTP status code provides a status of the request. The following table contains a list of returned status codes, descriptions, and the type of HTTP request that can generate the status code.
Status code | HTTP name | Description |
200 | OK | Success. |
201 | Created | The server has started the operation. |
202 | Accepted | The request has been accepted for processing, but the processing has not been completed. |
204 | No content | The request was successful, but the response does not exist. |
400 | Bad request | Required HTTP header was not specified. |
401 | Unauthorized | The operation is not authorized. |
403 | Forbidden | The server failed to authenticate the request. |
404 | Not found | The specified resource ID is not valid or the resource does not exist. |
404 | Not found | The specified storage system ID is not valid or the storage system does not exist. |
409 | Conflict | The specified resource type does not match the existing resource type. |
412 | Precondition failed | The server does not meet one of the preconditions that the requester put in the request. |
503 | Service unavailable | The server is currently unable to receive requests. Retry your request. |
504 | Gateway timeout | The request timed out waiting for a response. The Storage Advisor is not able to connect to the node. |