Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

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

Supported 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:

  • GET jobs with a specific username: https://ipAddress/v1/jobs?q=user:username
  • GET jobs with tags: https://ipAddress/v1/jobs/tags?q=tag:server)
  • GET jobs with ascending sorting of startDate: https://ipAddress/v1/jobs?sort=startDate:asc
  • GET calls can be combined: https://ipAddress/v1/jobs?q=user:username&sort=startDate:asc. This call searches for jobs with user = username and sorts them in ascending order by startDate
  • Filters may also be combined with each other using AND or OR operators, and ranges of numbers can be specified using TO: https://ipAddress/v1/jobs?q=(status:(IN_PROGRESS OR SUCCESS) AND startDate:[now-1d TO now])
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.

  • File storage management resources
  • Account domain resources
  • Role mapping resources
  • Token resources
  • Fabric switch resources
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.

  • File storage management resources
  • Account domain resources
  • Role mapping resources
  • Token resources
  • Fabric switch resources

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
  • Addition, administration, and deletion of servers, storage system, and fabric switches, SNMP manager, and tier management.
  • Addition, administration, and deletion of parity groups.
  • Addition, administration, and deletion of virtual file server resource groups.
  • Read-only privileges to monitor everything in Storage Advisor.
  • Registration of Data Instance Director in Storage Advisor.
Storage administrator
  • Addition, administration, and deletion of pools.
  • Addition, administration, and deletion of volumes, including creating, attaching to hosts, and data protection.
  • Addition, administration, and deletion of port configurations.
  • Read-only privileges to monitor everything in Storage Advisor.
Security administrator
  • Addition, administration and deletion of remote account domains.
  • User role assignment to groups.
  • Read-only privileges to monitor everything in Storage Advisor.
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.

 

  • Was this article helpful?