HPE Storage Tech Insiders
cancel
Showing results for 
Search instead for 
Did you mean: 

Enhanced REST API in Nimble OS 4

jcates98

The Nimble REST API has come a long way since it's introduction in Nimble OS version 2.3.  That version was the initial rollout of the REST API, intended to eventually completely replace the previous SOAP API.  (In case you missed it, I wrote an introductory blog post covering the NOS 2.3 REST API here.). While it was very useful and covered many object sets, there was still much work to be done.  Nimble OS 3 built upon this by introducing several new object sets, providing even more functionality.  Which brings us today to Nimble OS 4 which contains the most complete REST API set yet, with more object sets supported than ever before.  Not only that, but you'll also find that for many objects, new attributes have been added - while still maintaining backwards compatibility with the objects in previous Nimble OS versions. Finally, many object sets support actions which go beyond the typical CRUD operations - create, read, update, and delete.  Let's take a look at each of these in turn.

Object Sets

As always, the best way to explore the Nimble REST API is through the online REST API Reference. There you'll find not only the object sets referenced here, but all the relevant information you can get from them and the actions you can perform on them. To give you an idea of what's available as of Nimble OS 4, take a look at the following table:

access_control_records

active_directory_memberships

alarms

application_categories

application_servers

arrays

audit_log

chap_users

disks

events

fibre_channel_configs

fibre_channel_initiator_aliases

fibre_channel_interfaces

fibre_channel_ports

fibre_channel_sessions

folders

groups

initiator_groups

initiators

jobs

snapshot_collections

snapshots

software_versions

space_domains

subnets

tokens

user_groups

users

versions

volume_collections

volumes

New Attributes

While I won't spoil all the fun of exploring the API and finding out for yourself what is available, I do want to point out that many object sets contain new and useful attributes which weren't present when the original REST API rolled out. Have I mentioned the REST API Reference?  You'll find everything nicely documented there.  But how about an example in the meantime?  Certainly.  Let's take a look at the venerable "volumes" object set.  We'll grab a sample from the API reference and look at a "volumes" object in JSON format:


{
  "data" : {
  "serial_number" : "5596fd1da1c87b8d6c9ce900d3040000",  "block_size" : 4096,
  "warn_level" : 80,
  "dest_pool_id" : "",
  "pool_id" : "0a00000000000004d3000000000000000000000001",
  "snap_usage_compressed_bytes" : 0,
  "name" : "vol0.762157726640911",
  "last_modified" : 1426776077,
  "snap_usage_populated_bytes" : 0,
  "perfpolicy_id" : "0300000000000004d3000000000000000000000001",
  "num_connections" : 0,
  "description" : "",
  "move_bytes_migrated" : 0,
  "iscsi_sessions" : null,
  "app_uuid" : "",
  "num_fc_connections" : 0,
  "agent_type" : "none",
  "pool_name" : "default",
  "multi_initiator" : false,
  "base_snap_name" : "",
  "size" : 100,
  "perfpolicy_name" : "default",
  "owned_by_group" : "g1a1",
  "snap_limit" : 9223372036854775807,
  "snap_limit_percent" : -1,
  "move_start_time" : 0,
  "encryption_cipher" : "none",
  "total_usage_bytes" : 0,
  "vol_usage_compressed_bytes" : 0,
  "snap_usage_uncompressed_bytes" : 0,
  "snap_reserve" : 0,
  "volcoll_name" : "",
  "projected_num_snaps" : 0,
  "full_name" : "",
  "online" : true,
  "cache_policy" : "normal",
  "vol_state" : "online",
  "num_snaps" : 0,
  "cache_pinned" : false,
  "clone" : false,
  "read_only" : false,
  "reserve" : 0,
  "creation_time" : 1426776077,
  "id" : "0600000000000004d3000000000000000000000005",
  "metadata":[
  {"key":"key1","value":"val1"},
  {"key":"key2","value":"val2"}
  ],
  "caching_enabled" : true,
  "snap_warn_level" : 0,
  "thinly_provisioned" : true,
  "move_aborting" : false,
  "move_bytes_remaining" : 0,
  "fc_sessions" : null,
  "num_iscsi_connections" : 0,
  "offline_reason" : null,
  "pinned_cache_size" : 0,
  "online_snaps" : null,
  "access_control_records" : null,
  "parent_vol_name" : "",
  "cache_needed_for_pin" : 104857600,
  "limit" : 100,
  "target_name" : "iqn.2007-11.com.storage:vol0.762157726640911-v00000000000004d3.00000005.000004d3",
  "volcoll_id" : "",
  "usage_valid" : true,
  "search_name" : "vol0.762157726640911",
  "vol_usage_uncompressed_bytes" : 0,
  "parent_vol_id" : "",
  "base_snap_id" : "",
  "dest_pool_name" : "",
  "upstream_cache_pinned" : false,
  "folder_id": "",
  "folder_name": "",
  "avg_stats_last_5mins": {
  "read_iops": 10,
  "read_throughput": 11,
  "read_latency": 20,
  "write_iops": 25,
  "write_throughput": 90,
  "write_latency": 10,
  "combined_iops": null,
  "combined_throughput": 100,
  "combined_latency": 90
  }
  }
}

OK, now admittedly that's a ton of information to wade through.  I was hoping that something towards the end might have caught your eye, though.  See it there?  Just at the end.  Yep, finally some volume performance data that's available via the API!  The avg_stats_last_5mins attribute returns an array of performance metrics which gives you an insight into how the volume has been faring in terms of IOPS, throughput, and latency. That's certainly new!  And a welcome addition, I might add.

Now, to the best of my knowledge none of the already existing attributes have been removed. So, existing automation should work just fine.  Now though, you'll have even more detail to work with once you decide to take advantage of it.

Actions

Not everything can easily be framed in terms of CRUD - create, read, update, delete. Now many of the object sets support custom actions. Let's take a look at another example object set - this time we'll use "replication_partners".  The operations for "replication_partners" are as follows:

Create 

Delete 

Pause  

Read   

Resume 

Test   

Update

As you can see, in addition to the CRUD operations we now have Test, Pause, and Resume.  Each of these would be POST operations using the following URI format:

https://yourarray:5392/v1/replication_partners/id/actions/[test|pause|resume]

You probably saw it coming a mile away that I would point you towards the REST API Reference for further detail.  You're getting good at this.  Go forth now, and automate all the things.

About the Author

jcates98

Events
See posts for
dates/locations
HPE at 2018 Technology Events
Learn about the technology events where Hewlett Packard Enterprise will have a presence in 2018.
Read more
See posts for dates/locations
Reimagine 2018
Join us at one of the Reimagine 2018 stops and see how we Simplify Hybrid IT, innovate at the Intelligent Edge and bring it all together with HPE Poin...
Read more
View all