Difference between revisions of "+ Developer Guide Overview"

Latest revision as of 14:33, 11 April 2023

Overview

QuantaStor was designed from the start with a service oriented architecture so that all aspects of system, cluster, and storage grid configuration may be automated. There are multiple ways to automate QuantaStor management operations including the REST API, CLI, Ansible modules, and SOAP. The Developer Guide focuses on integration with QuantaStor via the REST APIs.

Supported Languages

You can use just about any programming language you like to communicate with QuantaStor via our RESTful API. Recommended tools:

• C/C++ - libcurl
• Python - PyCurl
• Unix/Linux/VMware/XenServer scripting - curl
• PHP - curl

Browser Tools

We highly recommend installing a tool like JSONView or other similar browser tool so that you can view the JSON output from the various API calls in an easy to read format. When experimenting with various APIs you can then use your browser to call the API, see the results, and plan for how to integrate it into your script or application.

Examples

Here's are some examples of how to enumerate various objects using the RESTful API and the curl utility:

curl -u admin:password https://192.168.0.116:8153/qstorapi/hostEnum -k
curl -u admin:password https://192.168.0.116:8153/qstorapi/storageVolumeEnum -k
curl -u admin:password https://192.168.0.116:8153/qstorapi/storageSystemGet -k
curl -u admin:password https://192.168.0.116:8153/qstorapi/storagePoolEnum -k
curl -u admin:password https://192.168.0.116:8153/qstorapi/userEnum -k
curl -u admin:password https://192.168.0.116:8153/qstorapi/networkShareEnum -k

One quick way to test is to just enter one of these URLs (https://192.168.0.116:8153/qstorapi/hostEnum) into your web browser which will work as long as your system admin account is still using the default password. Pretty much every known language has a curl type library/module for it so the above technique will work everywhere, you just need to get up to speed with your preferred language's curl API mechanism.

Note you can even access APIs using wget which in this example will store the results into a file called hostEnum:

wget --no-check-certificate https://192.168.0.135:8153/qstorapi/hostEnum

Passing Args as a File

You can also call one of our RESTful APIs by passing a file instead of command line arguments. To do this your command will look something like this:

curl -k -u admin:password -d @file.json  https://192.168.0.116:8153/qstorapi/jsonrpc

An example of how the file should be formatted looks like this:

{
    "method": "echo",
    "params": {
        "inputMessage": "Message"
    }
}

The format being used is JSON. You specify the command you would like to call using the key "method". Then the parameters are passed in using the key "params". If more than one parameter is specified, separate them with a comma.

{
    "method": "command",
    "params": {
        "param1": "<value1>",
        "param2": "<value2>",
        "param3": "<value3>"
    }
}

Reflection

The RESTful API has basic support for reflection, meaning that you can learn about all the arguments for a given API just by calling it with the 'help' parameter like so:

curl -k -u admin:password https://192.168.0.116:8153/qstorapi/hostAdd?help

Calling APIs with Parameters

To call an API with parameters you'll need to add a & between each parameter you specify and a ? between the API name and the start of the parameters like so:

curl -k -u admin:password "https://192.168.0.116:8153/qstorapi/hostAdd?iqn=iqn.1991-05.com.microsoft:osn-mediaserver3&hostname=mediaserver3&flags=0"

Which will return JSON output like this (note the quotes so that the ampersand is not interpreted by the shell). Also note that sometimes it can be hard to read the JSON output so we recommend using a JSON Formatter when you're developing your integration code.

{
   "task":{
      "i18nDescription":{
         "messageText":null,
         "messageId":null
      },
      "operation":"add",
      "id":"ca54a531-6386-a4f7-b9de-30f505329bb1",
      "objectType":"Host",
      "finishTimeStamp":"1969-12-31 16:00:00",
      "isRemote":false,
      "createdTimeStamp":"2012-08-23 21:53:40",
      "state":0,
      "acls":[
         {
            "reserved":0,
            "objectId":"ca54a531-6386-a4f7-b9de-30f505329bb1",
            "ownerType":23,
            "ownerId":"252d4786-b19f-ae43-1ff6-453bee8a652e",
            "accessLevel":2,
            "objectType":16
         }
      ],
      "clientIpAddress":"127.0.0.1",
      "parentId":null,
      "modifiedByUserId":null,
      "progress":0,
      "customId":null,
      "type":16,
      "description":"Adding host 'mediaserver3' to service with iSCSI initiator IQN 'iqn.1991-05.com.microsoft:osn-mediaserver3'.",
      "errorMessage":{
         "function":null,
         "severity":0,
         "errorCode":0,
         "file":null,
         "message":{
            "messageText":null,
            "messageId":null
         },
         "line":0
      },
      "modifiedTimeStamp":"1969-12-31 16:00:00",
      "storageSystemId":"50ce62e6-6846-c5b3-d8a1-27061a696604",
      "createdByUserId":"252d4786-b19f-ae43-1ff6-453bee8a652e",
      "name":"Add Host",
      "startTimeStamp":"2012-08-23 21:53:40",
      "taskState":2
   },
   "obj":{
      "username":null,
      "storageSystemId":"50ce62e6-6846-c5b3-d8a1-27061a696604",
      "isRemote":false,
      "hostGroupId":null,
      "name":"mediaserver3",
      "ipAddress":null,
      "createdByUserId":"252d4786-b19f-ae43-1ff6-453bee8a652e",
      "modifiedTimeStamp":"1969-12-31 16:00:00",
      "createdTimeStamp":"2012-08-23 21:53:40",
      "state":0,
      "hostOsType":0,
      "initiatorPortList":[
         {
            "storageSystemId":"50ce62e6-6846-c5b3-d8a1-27061a696604",
            "isRemote":false,
            "hostId":"4fb8c2da-235a-18f9-2620-1d8aa5da89c5",
            "name":"iqn.1991-05.com.microsoft:osn-mediaserver3",
            "ipAddress":null,
            "createdByUserId":"252d4786-b19f-ae43-1ff6-453bee8a652e",
            "modifiedTimeStamp":"1969-12-31 16:00:00",
            "createdTimeStamp":"2012-08-23 21:53:40",
            "wwpn":null,
            "state":0,
            "iqn":"iqn.1991-05.com.microsoft:osn-mediaserver3",
            "initiatorType":0,
            "modifiedByUserId":null,
            "customId":null,
            "type":13,
            "id":"535abed2-830a-a437-d6fd-5af7c5b5c263"
         }
      ],
      "modifiedByUserId":null,
      "customId":null,
      "password":"********",
      "type":11,
      "id":"4fb8c2da-235a-18f9-2620-1d8aa5da89c5",
      "description":"None"
   }
}

Async vs. Sync (blocking vs non-blocking) API calls

All of the APIs for QuantaStor that modify the configuration in any way will start a task in the system. If you call any API with the flags parameter set to 0 it'll be treated as a blocking call which wait for the task to complete before returning. If you want to call the function and have it return immediately you can pass a 1 as the flags parameter which indicates to the server that the caller wants this to be an asynchronous non-blocking call. With asynchronous calls you'll get the task object back so that you can use the taskGet API to monitor the progress of the operation. When the task completes it will populate the customId property of the task to contain the ID(s) of the objects which were created/deleted/modified by the task.

Task Monitoring

As indicated above, sometimes you'll want to call an API asynchronously so that you can monitor the progress of the task and/or because you want to queue up multiple operations to run simultaneously. In such cases where you call an API asynchronously (flags=1) you can monitor the progress of the task using the tastGet API or the tastEnum API if you want to see all running tasks. When the task is completed you can check the customId property to see the ID(s) of the objects created/modified.

API Error Code Definitions

For all APIs a 0 is returned for SUCCESS and a non-zero error code is returned if there is a command failure along with a description of the error. Full list of error codes are available here.

Security

QuantaStor REST interface always uses SSL via HTTPS. You can change the pem keys on your system by replacing the qstorapi_server.pem file located in /opt/osnexus/quantastor/restsrv/ with your own. If you want to use plain HTTP without SSL you can rename or remove the qstorapi_server.pem and the RESTful service will automatically fall back to using HTTP. After removing the file just restart the RESTful service interface with:

service restsrv restart

If you want to block access to the restful interface you can stop the service and/or you can remove access to port 8153 by removing the entry associated with that port number from the /etc/init.d/iptables configuration file and then restart iptables like so:

service iptables restart

In a similar manner you can block access to the web management interface on port 80/8080.

Supported SOAP / WebServices Implementations

• gSOAP (C++, all platforms)
• Apache Axis (Java, all platforms)
• .NET (C# & Visual Basic, Windows)

API List

The following represents the full API list for every API in QuantaStor. Nothing is left out, if you can do it from the web management interface or the CLI, it's here.

Examples

 
curl -u username:password -k https://hostname:8153/qstorapi/aclAdd?objectId=<id>&ownerType=<int>&ownerId=<id>&accessLevel=<int>&objectType=<int> 

curl -u username:password -k https://hostname:8153/userAdd?username=tiger&password=passWORD1&firstName=Tiger&lastName=Woods&role=Administrator

curl -u username:password -k -d @data.json https://hostname:8153/qstorapi/jsonrpc

Example Script

Here is an example script in python. To use this example replace the ip address with your QuantaStor boxes ip.

import json
import subprocess

print "I am getting the storage system info..."
#To get the data make an http request (such as a curl call)

proc = subprocess.Popen(["curl", "-k", "-u", "admin:password",
         "https://192.168.0.142:8153/qstorapi/storageSystemGet?"], stdout=subprocess.PIPE)

(out, err) = proc.communicate()

print
print "Here is what the returned data looks like when I get it:"
print
print str(out)
print

#call json.loads to turn it into a python dictionary
out = json.loads(out)
print "Here is how to get a single field from the output:"
print
storageSystemId = out["id"]
print storageSystemId

QuantaStor REST API Reference Guide

All efforts are made to keep existing REST API from changing but on rare occasions API changes to existing APIs and objects may change. As such the following sections document the APIs as per a specific released version of QuantaStor. New versions of QuantaStor generally introduce some new APIs and object types but these are added in a backwards compatible fashion.

Current Version

Archived Versions

QuantaStor REST API Reference v5.2

QuantaStor REST API Reference v4.2, v4.1

QuantaStor REST API Reference v4.0 and earlier

Enumeration Types

The enumeration types listed below are used with APIs noted above. Many of the enumerations have assigned values like "OSN_CMN_FLAG_ASYNC = 0x0001" but for those that do not have assigned values note that they are 0 indexed. For example, OSN_CMN_ACCESSTYPE_READWRITE should be specified as 0 and OSN_CMN_ACCESSTYPE_READONLY specified as a 1 to the storageVolumeModify API as the accessMode for changing the configuration of a storage volume.

• QS API Enumerations v5.5

Ansible Documentation

Currently, OsNexus does not package the python client or the Ansible modules with the QuantaStor installation package. Individual installation instructions can be found on GitHub (Ansible modules) and PyPi (qsclient).

OSNEXUS Python client in Git: OSNEXUS QSPyClient

OSNEXUS QuantaStor Python Client Library

OSNEXUS Ansible Modules in Git: OSNEXUS qsansible

For more information about QuantaStor Ansible automation,
checkout our blog post Automating storage provisioning using Ansible with Quantastor.