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