Originally posted by: Daniel Wendler
IBM Spectrum Protect Plus is a modern Data Protection and Data Reuse solution focused on Virtual Environments and Applications. This article provides an overview of the Spectrum Protect Plus REST API and explains how to get started with the API. We highlight the need to get involved with the REST API as it offers wide capabilities such as monitoring, configuration, automation and administration of Spectrum Protect Plus (SPP) environments without utilizing the Graphical User Interface (GUI). We will demonstrate how to explore and use the API and explain which tools are useful for exploration and interaction. General purpose tools like cURL and JQ are introduced as well as a Python library called sppclient which simplifies the interaction for API operations like GET, POST, PUT and DELETE.
The necessity to have a deeper look at the SPP's REST API mostly becomes a hot topic when the Spectrum Protect Plus Environment is scaling out. Reasons why the GUI may not be always the perfect fit for every client need may be:
- increasing number of Hypervisors and VMs to configure and protect
- amount and variety of applications
- quantity of VSNAPs and VADPs
- the need to check in an automated way the SLA's status, i.e. if it failed, if it ended partial or completed successful
- monitoring the SPP environment in terms of resource utilization (capacity, CPU, RAM, SNAP capacity), job logs and warnings or error messages
The IBM Spectrum Protect Plus (SPP) REST API comes in place to enable administrators to use existing REST capable tools or to implement their own tools and scripts and integrate them into the operating workflows. RESTful (REpresentational State Transfer) APIs use stateless protocols where the client holds the session state. RESTful clients send requests to a resource URI and expects a response i.e. in HTML, XML, JSON, or some other formats. The SPP API is sending responses in JSON (Java Script Object Notification) and implements a subset of four basic HTTP methods for applications to interact with: GET, POST, PUT, and DELETE.
How to get started with the API:
|
Basically as of today there are two documentations available. The first one is the IBM Spectrum Protect Plus Version 10.1.1 REST API Developer Guide . The REST API PDF documents the essentials of REST and is a good starting point to understand session handling and the four basic HTTP methods for applications to interact with: GET, POST, PUT, and DELETE. Further it contains several RESTful SPP API examples that demonstrate interaction, basic functions such as getting a session ID, assigning a VM, and starting a job and the expected return values.
Secondly the most recent and up-to-date documentation is the Swagger UI Tool. In SPP version 10.1.3 the Swagger UI Tool has been integrated into the GUI for interaction with the API. Swagger is an open-source framework with tools to develop, build, document and query REST APIs. Some screenshots with available endpoints, sample queries and results will be show later in the examples section.
|  |
Explore the API:
- cURL and JQ
- Swagger UI Tool
- use of sppclient with Python scripts
1. cURL and JQ
REST APIs can easily be queried using general purpose tools like cURL to transfer data using URL syntax . JQ is as a lightweight and flexible command-line JSON processor for formatting, filtering and transformations. The following two curl commands are required to obtain a session ID and secondly to request site information from the API with the session ID as additional header:
command: curl -sS -k -X POST -H 'Accept:application/json' -H 'Content-type:application/json' --user "testuser:pass4AP!" https://spphost/api/endeavour/session | tr ',' '\n' | grep sessionid
response: {"sessionid":" a1d0bb323aae48389ae5cf3e21ac4c94 "
curl -sS -k -X GET -H 'Accept:application/json' -H 'Content-type:application/json' -H 'x-endeavour-sessionid: a1d0bb323aae48389ae5cf3e21ac4c94' -H 'x-endeavour-auditrequest:false' https://spphost/api/site | jq '.'
2. Swagger UI Tools
The screenshots show a list available documented API categories. In the example below we query the available sites with their attributes. By selecting the endpoint and the desired operation the user can try out the command. A GET operation will not make any changes to the configuration so this is a good start to explore the responses and the response format....
3. use of sppclient
The sppclient is a Python project provided by the Spectrum Protect Plus development team. It can be obtained from Github (https://github.com/sppautomation/sppclient ). The client is provided AS-IS without guarantee to run and with no support. The project is a collection of modules (sppclient) and more than 20 examples for SPP REST API scripts written in Python.
The integration of the sppclient ease interaction with SPP's REST API and is intended for testing, monitoring and automation. The module is registered in PyPI and can be installed with all module requirements with the command: pip install sppclient
The table below lists scripts which are bundled with the sppclient package provided by the SPP development team:
- appassigntosla.py
- changeuserpassword.py
- createsite.py
- deletesite.py
- createslapolicy.py
- filerestore.py
- get_sessions.py
- joblist.py
- registerhypervisor.py
- registervsnap.py
- runjob.py
- spplogcollect.py
- sppvmbackupinfo.py
- sqlcopies.py
- sqlrestore.py
- validatevsnapstatus.py
- vmware_chargeback.py
- vmwareassigntosla.py
- vmwaretestrestore.py
Further on we have recently contributed in the project and have added the following new scripts:
get_alerts.py
Displays the alerts (see GUI alerts), can be sorted with DESC, ASC by timeframe and search string.
storageList.py
Lists the status of all VSNAPs with details like total capacity, used capacity, free space, etc...
systemInfo.py
Inspired by Spectrum Protect "q system", a base information about the SPP system, i.e. CPU utilization, dedup ratio, storage utilization and catalog backup status:
getJSON.py
A script to query the API endpoint and receive response in pretty format, raw or filtered, accepts filter and sort arguments in order to build the proper URIs.
simple_request.py
Purpose of this script is to demonstrate the basic steps to interact with a REST API without sppclient.
Summary
For various aspects in the day-to-day business of using Spectrum Protect Plus the REST API could be helpful to simplify and automate repeating tasks and monitoring activities. The sppclient project is a convenient and easy way forward to implement script-based solutions for Spectrum Protect Plus, where everyone could participate and contribute.
#DS8000