lm_rest 1.0.5 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c01ece27d96964546705d1d5a610b33e5a5c173d63a44f9a20252846192cb23
-  data.tar.gz: 8ab3dc099b5088d46d0d752de09c73a273a662d17b05b2a753363f6f9498ed6b
+  metadata.gz: 3a4f87a7e7c93fa4a82609673f1f8e2d83838a4a66204aaff72c9bf4009dcaf6
+  data.tar.gz: b9c12122bab2c4d6dabfa8d3edefcd60e863d082238c0e456c50dd86ef15ce27
 SHA512:
-  metadata.gz: c6180a42bdb7fdd738651da70f41c5a4158dd5ecd177e37bc45ce67434f4ec711183743526dea241d0a99ab73c247bfd13d879cf8119c5b89af88250c9f81f35
-  data.tar.gz: b9e563ccf97f75174a23dd88e4d58222fa40b58a1078a22ba06d2f199ae8252cd8ed4249b007ee1efbbaa3b73c3c30fe43edde48bd395d962d41e78c6751e005
+  metadata.gz: 8b33d7e50310ea6f7a1d679f8bf4385839c3226b41830ef513ada313423aa6b2227988f40e1403e4e05be56d5d96fd51af8008a451311faec1d498ff4b990576
+  data.tar.gz: f2553bdb581abd17695a47e56aa23bf5790272a3ad57475ae42dd13b92a19a786ae404e09acecf40a43b3bd14bc4ebc8aeba11d31edbb648871a51394e399426

data/README.md

@@ -2,6 +2,10 @@
 
 An Unofficial Ruby gem for the LogicMonitor REST API.
 
+[![Gem Version](https://badge.fury.io/rb/lm_rest.svg)](https://badge.fury.io/rb/lm_rest)
+
+[LogicMonitor REST API v3 Swagger Docs](https://www.logicmonitor.com/support/rest-api-v3-swagger-documentation)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,29 +22,57 @@ Or install it yourself as:
 
 `$ gem install lm_rest`
 
+## Remove system.categories
+
+If you accidentally applied system.categories all over your LogicMonitor
+environment, or just need to clean out some old categories, there's an included
+demo script just for you.
+
+Install this gem, then check in the `/bin` folder of this repo for the
+`system_category_cleaner.rb` script. It's very simple, you'll just need to pass
+it the following arguments in order, preferrably in single quotes:
+* Your portal name, like `'hooli'`
+* Your API access ID like `'long_api_access_id'`
+* Your API access Key like `'long_api_access_key'`
+* The AppliesTo matching devices you want to scrub like
+  `'hascategory("collector")&& system.collectorversion>=24106'`
+* The category you want to remove, like `'BadCategory'`
+
+Your devices should be all cleaned up. The script will respect rate limits and
+it splits all system.categories on ',' before removing the entry you specify.
+
+It should go without saying that this is unofficial, unsupported, and may mess
+your system up even more.
+
+
 ## Supported API Resources
 
-Every API resource is defined in the `api.json` file and its associated defined
-methods are supported. You can easily add your own if you can't wait for me
-to update this.
+Every API resource and operation is defined in `api.json`, which is generated
+from the LogicMonitor REST API v3 Swagger surface. Generated operation methods
+and legacy convenience aliases are both supported.
 
-Each method (`get_*, add_*, update_*, delete_*`) works the same
-for each resource. Each method name follows the pattern `method_resource`.
+Each method (`get_*, add_*, update_*, delete_*`) works the same for each
+resource. Each method name follows the pattern `method_resource`.
 
-Every method except for `delete_*` will return an `LMRest::Resource` object.
-It is essentially just a PORO with dynamically created property accessors
-(constructed from the API JSON response). This makes it easy to access
-attributes, edit them, and update objects. You can get a `Hash` version of the
-object with `#to_h`.
+Every method except for `delete_*` returns `LMRest::Resource` objects. A
+resource is a hash-backed wrapper around the API JSON response with dynamic
+attribute-style access, so both `resource.name` and `resource['name']` work.
+Use `#to_h` to get a deep-copied `Hash` version suitable for updates.
 
-Note: This library handles pagination for you! Use `size` and `offset` request
-parameters and get sane results. Default `size` is the total number of existing
-objects. The default `offset` is 0.
+Paginated GET endpoints are handled automatically. If you omit `size`, the
+client will keep requesting pages until all items have been collected. If you
+set `size`, the client will fetch up to that many items even when it spans
+multiple 1000-item API pages. `offset` defaults to `0`.
 
 ## Usage
 
 See the example `ds_checker.rb` script in `bin` to get a better feel for how to
-use the gem.
+use the gem. It expects:
+
+* LogicMonitor account name
+* API access ID
+* API access key
+* Datasource name or filter glob
 
 ```ruby
 require 'lm_rest'
@@ -50,7 +82,7 @@ require 'lm_rest'
 
 lm = LMRest::APIClient.new('company', 'access_id', 'access_key')
 
-# returns array of Resource objects
+# returns all datasource resources across every API page
 lm.get_datasources
 
 
@@ -59,7 +91,9 @@ lm.get_datasource(721)
 
 
 # return array of Resource objects whose names begin with "VMware"
-lm.get_datasources(filter: 'name:VMware*')
+# NOTE: when using filter, you need quotes around the filter's "value":
+# This is incorrect in the LogicMonitor API docs as of this writing (8/10/2021)
+lm.get_datasources(filter: 'name:"VMware*"')
 
 
 # add a device to your account
@@ -105,6 +139,14 @@ lm.ack_collector_down(id, comment)
 lm.run_report(id)
 
 
+# Handle API failures without leaking response bodies to stdout
+begin
+  lm.get_device(999999)
+rescue LMRest::APIError => e
+  warn "#{e.status}: #{e.body}"
+end
+
+
 ```
 
 ## TODO