NexentaStor RESTful API

Reference Guide

4.0.1

3000-rest_api-v4.0-000041-A Copyright © 2014 Nexenta Systems, ALL RIGHTS RESERVED

Notice: No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or stored in a database or retrieval system for any purpose, without the express written permission of Nexenta Systems, Inc. (hereinafter referred to as “Nexenta”).

Nexenta reserves the right to make changes to this document at any time without notice and assumes no responsibility for its use. Nexenta products and services only can be ordered under the terms and conditions of Nexenta’ applicable agreements. All of the features described in this document may not be available currently. Refer to the latest product announcement or contact your local Nexenta sales office for information on feature and product availability. This document includes the latest information available at the time of publication.

Nexenta is a registered trademark of Nexenta in the United States and other countries.

All other trademarks, service marks, and company names in this document are properties of their respective owners. This document applies to the following product versions

Product Versions supported NexentaStor 4.0.1

ii NexentaStor RESTful API Reference Guide Contents

Preface ...... v

1 Introduction ...... 1 About NexentaStor Restful APIs ...... 1 REST Format ...... 1 About NexentaStor REST Requests ...... 2 Enabling Usage of REST API ...... 3 JSON Request Fields ...... 4

2 Examples of RESTful API requests ...... 5 Receiving the list of folder names ...... 5 Requesting Folder’s Quota ...... 5 Setting Up a Quote for a Folder ...... 6 Example of a Response with an Error Message ...... 6

3 Examples of Python Scripts ...... 7

NexentaStor RESTful API Reference Guide iii This page intentionally left blank

iv NexentaStor Restful API Reference Guide Preface

This documentation presents information specific to Nexenta products. The information is for reference purposes and is subject to change.

Intended Audience

This documentation is intended for Network Storage Administrators and assumes that you have experience with data storage concepts, such as NAS, SAN, NFS, and ZFS.

Documentation History

The following table lists the released revisions of this documentation.

Table 1: Documentation Revision History

Revision Date Description

3000-rest_api-v4.0-000041-A April, 2014 GA

Contacting Support

Choose a method for contacting support: • Visit the Nexenta customer portal http://nexenta.force.com/ customerportal or partner portal http://nexenta.force.com/ partnerportal. Log in and browse a knowledge base. • Using the NexentaStor user interface, NMV (Nexenta Management View): a. Click Support. b. Complete the request form. c. Click Send Request. • Using the NexentaStor command line, NMC (Nexenta Management Console): a. At the command line, type support. b. Complete the support wizard.

NexentaStor RESTful API Reference Guide v Preface

Comments

Your comments and suggestions to improve this documentation are greatly appreciated. Send any feedback to [email protected] and include the documentation title, number, and revision. Refer to specific pages, sections, and paragraphs whenever possible.

vi NexentaStor RESTful API Reference Guide 1

Introduction

This section includes the following topics: • About NexentaStor Restful APIs • About NexentaStor REST Requests • Enabling Usage of REST API • JSON Request Fields

About NexentaStor Restful APIs

Representational State Transfer (REST) is an architectural style for distributed network systems. REST uses existing Web technologies and

protocols, such as HTTP and XML. The largest known implementation of a system conforming to the REST architectural style is the Internet. REST-style architectures implements the client-server model in which service requesters, called clients, initiate requests to service or resource providers, called servers. Servers process requests from clients and return applicable responses. NexentaStor implements RESTful style architecture based on HTTP protocol. RESTful way of executing NexentaStor remote functions maximizes the use of the pre-existing, well-defined interface, and other built-in capabilities of third-party applications, as well as minimizes the addition of new application-specific features on top of it.

REST Format

NexentaStor REST-style call supports JSON (JavaScript Object Notation) requests through HTTP POST method. Plain HTTP and XML requests are not supported.

See Also:

• http://www.json.org/JSONRequest.html

NexentaStor RESTful API Reference Guide 1 Introduction

About NexentaStor REST Requests

Depending on the type of the D-Bus call, REST-style request is sent either to /rest/nms or to /rest/nmdtrace. The body of the request must contain JSON encoded entity. For the purpose of simplicity, in all examples in this document requests are sent to /rest/nms. If you need to receive parameters from nmdtrace, change the path in the body of the JSON request to /rest/nmdtrace. All JSON requests must contain HTTP Basic authorization header with base64 encoded username and password. Example: "Basic " + base64(username + ":" + password)

When creating a REST request, use the NexentaStor Storage API methods described in the NexentaStor Storage Appliance API User Guide. You must replace the name of the NMS object from the SA-API document with the REST Object name from the following table: Table 1: Correspondence between NMS and REST API Object Names

NMS object DBus name REST Object name

Appliance /Root/Appliance appliance ApplGroup /Root/ApplGroup appl_group SmfAutoService /Root/Smf/AutoService autosvc SmfAutoScrub /Root/Smf/AutoService/ auto_scrub AutoScrub SmfAutoSnap /Root/Smf/AutoService/ auto_snap AutoSnap SmfAutoTier /Root/Smf/AutoService/AutoTier auto_tier Collector /Root/Runner/Collector collector Folder /Root/Folder folder Iscsi /Root/Iscsi iscsi Mailer /Root/Mailer mailer LogViewer /Root/LogViewer logviewer Jbod /Root/Jbod jbod Lun /Root/Lun lun Runner /Root/Runner runner Trigger /Root/Runner/Trigger trigger Reporter /Root/Runner/Reporter reporter Indexer /Root/Runner/Indexer indexer Network /Root/Network network NetworkStorageService /Root/NetworkStorageService netstworksvc

2 NexentaStor RESTful API Reference Guide Introduction

Table 1: Correspondence between NMS and REST API Object Names

NMS object DBus name REST Object name NetworkInterface /Root/Network/Interface netif Syspool /Root/Syspool syspool Server /Root/Server server Volume /Root/Volume volume Zvol /Root/Zvol zvol Snapshot /Root/Snapshot snapshot Smf /Root/Smf smf SmfNetworkService /Root/Smf/NetworkService netsvc Plugin /Root/Plugin plugin Job /Root/Job job Support /Root/Support support

See Also:

• Product Documentation • NexentaStor Storage API Reference Guide

Enabling Usage of REST API

You must enable the usage of REST API for the selected user so he or she can execute REST requests.  To enable the usage of REST API: 1. Click Settings > Users. 2. Select a user. 3. In the NMV GUI Permissions pane, select the Can_use_restapi check box. 4. Click Save.

NexentaStor RESTful API Reference Guide 3 Introduction

JSON Request Fields

The following table describes JSON request fields. Table 2: JSON Request Fields

Field Description object The string name of the object which method you call. If you specify a plugin, you can leave this field blank. method String name of a method. params An array of parameters that is transferred to method. plugin Name of a plugin. Optional parameter. Specify the full name of the plugin. For example: nms-autosync. Example of a JSON request: {"params": [""], "method": "get_worm", "plugin": "nms-worm"} result JSON-serialized output of method execution. NMS may return the Null value if the request has been proceeded with an error. error String contains a field with a text message about the error. Otherwise, contains the Null value. tg_flash Service field for adding Turbogears.

4 NexentaStor RESTful API Reference Guide 2

Examples of RESTful API requests

This section includes the following topics: • Receiving the list of folder names • Requesting Folder’s Quota • Setting Up a Quote for a Folder • Example of a Response with an Error Message

Receiving the list of folder names

Request {"object": "folder", "params": [""], "method": "get_names"}

Response {"tg_flash": null, "result": ["vol1/test/w8", "vol1/ping", "vol1/ ping/w1", "vol2", "vol1/test/w16", "vol1/test/w1", "vol1/test/ w11", "vol1/test/w9", "vol1/test/w7", "vol1/test/w100", "vol1/ test/w5", "vol1/test/w18", "vol1/test/w12", "vol1/test/w13", "vol1", "vol1/test/w2", "vol1/test/w19", "vol1/test/w20", "vol1/ test", "vol1/test/w10", "vol1/test/w6", "vol1/q", "vol1/test/w3"], "error": null}

See Also:

• NexentaStor Storage Appliance API User Guide

Requesting Folder’s Quota

Request {"object": "folder", "params": ["vol1/q", "quota"], "method": "get_child_prop"} Response {"tg_flash": null, "result": "10G", "error": null}

See Also:

• NexentaStor Storage Appliance API User Guide

NexentaStor RESTful API 5 Examples of RESTful API requests

Setting Up a Quote for a Folder

Request {"object": "folder", "params": ["vol1/q", "quota", "99T"], "method": "set_child_prop"} Response {"tg_flash": null, "result": null, "error": null}

See Also:

• NexentaStor Storage Appliance API User Guide

Example of a Response with an Error Message

Request {"object": "folder", "params": [""], "method": "xxxxx"} Response {"tg_flash": null, "result": null, "error": {"message": "'NZAObject' object has no attribute 'xxxxx'"}}

See Also:

• NexentaStor Storage Appliance API User Guide

6 NexentaStor RESTful API 3

Examples of Python Scripts

You can write python scripts that request data from the NexentaStor API. The scripts must include json requests. The following Python script is an example of how you can receive a list of properties for folder archive/lists:

import urllib2 as u import json

url = 'http://10.3.60.111:2000/rest/nms' headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % 'admin:nexenta'.encode('base64')[:-1] } print headers data = json.dumps({'object': 'folder', 'method': 'get_child_props', 'params': ['archive/lists', 'refer']})

r = u.Request(url, data, headers) resp = u.urlopen(r)

print resp.info().status print resp.read()

You can use the iSCSI and NFS driver for OpenStack Cinder as an example application that uses REST-API. See: https://github.com/openstack/cinder/tree/master/cinder/volume/ drivers/nexenta

See Also:

• NexentaStor Storage Appliance API User Guide

NexentaStor RESTful API 7 Examples of Python Scripts

This page intentionally left blank

8 NexentaStor RESTful API Global Headquarters 455 El Camino Real Santa Clara, California 95050

Nexenta EMEA Headquarters Camerastraat 8 1322 BC Almere Netherlands

Nexenta Systems Italy Via Vespucci 8B 26900 Lodi Italy

Nexenta Systems China Room 806, Hanhai Culture Building, Chaoyang District, Beijing, China 100020

Nexenta Systems Korea Chusik Hoesa 3001, 30F World Trade Center 511 YoungDongDa-Ro GangNam-Gu, 135-729 Seoul, Korea

3000-rest_api-v4.0-000041-A