Getting Started with the Spectrum Scale REST API—

Andreas KoeningerScrum Master and DeveloperSpectrum Scale GUI and REST API

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Contents

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Overview 03What is a REST API? 04Four basic operations 05

Getting Started with the Spectrum Scale REST API 06Architecture 07Sample Calls 10Endpoints 11

Demo 17

What is a REST API?

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

“REST API”• “Representational State

Transfer”

• Neither a protocol nor a standard à Every API is different

• Some loose conventions, for example:

• Hierarchical URLs to identify entities, e.g.:

/filesystems/gpfs0/filesets

Stateless• Client always sends all the

data the server needs to fulfill a request

• Easy to use and implement since no state has to be managed

• On the CLI: curl

• Python, Java, …

HTTP/HTTPS• Well-known and wide-

spread protocol

• HTTP security features can be leveraged, e.g. encryption, authentication, …

• URLs are used to identify entities

• Four basic HTTP methods:

• POST, PUT, GET, DELETE

JSON/XML• Data is returned in machine

readable format, for example JSON (JavaScript Object Notation) or XML (Extensible Markup Language)

• Easy to read and debug

Update – PUT

• Change the configuration or state of an entity

• Example: Change an ACL or unmount a filesystem

Delete – DELETE

• Remove an entity

• Example: Delete a threshold or NFS export

Read – GET

• Retrieve information about all entities or a specific entity

• Returned entities can be filtered

• Example: List all unhealthy nodes

Create – POST

• Create new entities asynchronously

• Example: Create a new fileset or SMB share

Four basic operations

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Getting Started with the Spectrum Scale REST API

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Architecture 07Sample Calls 10Endpoints 11

GUI user and role management is used

à Local users or users in an external AD/LDAP server are supported

Data is cached in a local database

à Cached data is updated via events coming from GPFS and on periodic intervals

Uses the same software stack as the GUI

à Multiple instances are supported for HA

Requests are served over HTTPS

à Any client application can easily access the REST API (curl, Python, Java, …)

Architecture (1/3)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Architecture (2/3)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

DB

GPFS

GUI Backend Layer

REST APIGUI Frontend

ExperiencedStorage Admins

Custom Monitoring

Custom Management

Custom Configuration

New non-technical Users

GNR (ESS, Lenovo, DDN)

POST, PUT, DELETE requests are always asynchronous

• A jobId is returned which can be used to track the progress

• sysout, syserr, rc, .. of the mm-command can be retrieved

GET requests are always served from the local database

• Returned entities can be filtered (e.g. all filesets starting with research*)

• Returned fields can be filtered

Four basic operations:

• POST, PUT, GET, DELETE

Architecture (3/3)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Sample Calls

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

List all filesets in filesystem:

curl -u 'admin:admin001' -X GET -khttps://localhost:443/scalemgmt/v2/filesystems/gpfs0/filesets?fields=:all:

List all endpoints:

curl -u 'admin:admin001' -X GET -khttps://localhost:443/scalemgmt/v2/info

Documentation of all endpoints is available at:

https://<yourguihost>/ibm/api/explorer

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (CES, File Systems, ACLs, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (Disks, File Sets, Quotas, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (Policies, Snapshots, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (RGs, NFS exports, Node Classes, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (Health Data, Performance Monitoring, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Endpoints (SMB Shares, …)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Hello Mr. Storage Admin, I need storage space for our new research project. Can you help me?

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Sure!

Demo (GitHub: https://github.com/andiveloper/spectrumscale-guides)

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Thank you

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation

Andreas KoeningerScrum Master and DeveloperSpectrum Scale GUI and REST API—andreas.koeninger@de.ibm.comGitHub: https://github.com/andiveloper/spectrumscale-guidesLinkedIn: https://www.linkedin.com/in/andreas-k%C3%B6ninger-9a465283/

Spectrum Scale User Group / March 21, 2019 / © 2019 IBM Corporation