wavefront-sdk 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 424ff394e307dc912d9b323b522afd1a972fd79c
-  data.tar.gz: ad5f049f02bc52c96f4c7c09e13a68672f94e472
+  metadata.gz: 3a04d6dc9514eea460313e7caa056b80e679df99
+  data.tar.gz: 4c702f5ec963fa951c5d5b59b916784c12c4f9ec
 SHA512:
-  metadata.gz: '083f4d03c0b1e45f0c0b742fca39caead79fee037a326e6f0413e2e66461aafcf731e5ea3734f876b3079ff3f2d57b146aa86e88f1935c8aeee062eaa466e782'
-  data.tar.gz: 150d41f57564dd6a38d695719100f7e3f853dcdb3c6f991e924a2683effb81a4f209038656b81d7f9a4535fbb9281ee86e1aecb817e3f9c613180453a9b0bb47
+  metadata.gz: ecb2531e3b9e2507679abec131ac65d3688c3c959cace5203fe78853d6dec16358687221dc5500701b1d1cc5ec21835b81739a75d51a4720aaf033401eadad9b
+  data.tar.gz: ad79ef3b12a11f635bf0a6ab00e3c53aae58ce94a7885811fe13eba1fe59240f36abc2844faf46db73badfe97a165acd6254c33aff4b784df12d24dd4ae362ea

data/Gemfile.lock

@@ -1,9 +1,11 @@
 PATH
   remote: .
   specs:
-    wavefront-sdk (0.0.1)
+    wavefront-sdk (0.1.0)
+      addressable (~> 2.4)
       faraday (>= 0.12.1, < 0.13)
       inifile (>= 3.0.0)
+      map (~> 6.6.0)
 
 GEM
   remote: https://rubygems.org/
@@ -17,6 +19,7 @@ GEM
       multipart-post (>= 1.2, < 3)
     hashdiff (0.3.2)
     inifile (3.0.0)
+    map (6.6.0)
     minitest (5.8.5)
     multipart-post (2.0.0)
     parser (2.4.0.0)

data/README.md

@@ -1,4 +1,4 @@
-# wavefront-sdk [![Build Status](https://travis-ci.org/snltd/wavefront-sdk.svg?branch=master)](https://travis-ci.org/snltd/wavefront-sdk) [![Code Climate](https://codeclimate.com/github/snltd/wavefront-sdk/badges/gpa.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Issue Count](https://codeclimate.com/github/snltd/wavefront-sdk/badges/issue_count.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Known Vulnerabilities](https://snyk.io/test/github/snltd/wavefront-sdk/badge.svg)](https://snyk.io/test/github/snltd/wavefront-sdk)
+# wavefront-sdk [![Build Status](https://travis-ci.org/snltd/wavefront-sdk.svg?branch=master)](https://travis-ci.org/snltd/wavefront-sdk) [![Code Climate](https://codeclimate.com/github/snltd/wavefront-sdk/badges/gpa.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Issue Count](https://codeclimate.com/github/snltd/wavefront-sdk/badges/issue_count.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Known Vulnerabilities](https://snyk.io/test/github/snltd/wavefront-sdk/badge.svg)](https://snyk.io/test/github/snltd/wavefront-sdk) [![Gem Version](https://badge.fury.io/rb/wavefront-sdk.svg)](https://badge.fury.io/rb/wavefront-sdk) ![](http://ruby-gem-downloads-badge.herokuapp.com/wavefront-sdk?type=total)
 
 This is a Ruby SDK for v2 of
 [Wavefront](https://www.wavefront.com/)'s public API. It supports Ruby >= 2.2.
@@ -15,15 +15,29 @@ $ gem install wavefront-sdk
 
 or to build locally,
 
-```
+
 $ gem build wavefront-sdk.gemspec
 ```
 
+## Documentation
+
+The code is documented with [YARD](http://yardoc.org/) and
+automatically generated documentation is [available on
+rubydoc.info](http://www.rubydoc.info/gems/wavefront-sdk/).
+
 ## Examples
 
 First, let's list the IDs of the users in our account. The `list()` method
-will return a `Wavefront::Response::User` object with a list of items. Most
-response classes behave this way.
+will return a `Wavefront::Response` object. This object has
+`status` and `response` methods. `status` always yields a
+structure containing `result`, `message` and `code` fields which can
+be inspected to ensure an API call was processed successfully.
+`response` gives you a the JSON response from the API, conveniently
+processed and turned into a
+[`Map`](https://github.com/ahoward/map) object. Map objects can be
+interrogated in various ways. For instance `map['items']`,
+`map[:items]` and `map.items` will all get you to the same place.
+
 
 ```ruby
 # Define our API endpoint. (This is not a valid token!)
@@ -41,16 +55,24 @@ log = Logger.new(STDOUT)
 
 wf = Wavefront::User.new(CREDS, verbose: true, logger: log)
 
+# See how things went:
+
+p wf.status
+#<Wavefront::Type::Status:0x007feb99185538 @result="OK", @message="", @code=200>
+
+# And print each user's ID
+
 wf.list.response.items.each { |user| puts user[:identifier] }
 
-# And delete the user 'lolex@oldplace.com'
+# Now delete the user 'lolex@oldplace.com', disregarding the
+# response.
 
 wf.delete('lolex@oldplace.com')
 ```
 
 Retrieve a timeseries over the last 10 minutes, with one minute bucket
 granularity. We will describe the time as a Ruby object, but could also use
-an epoch timestamp.
+an epoch timestamp. The SDK happily converts between the two.
 
 
 ```ruby
@@ -63,9 +85,9 @@ Wavefront::Query.new(CREDS).query(
 )
 ```
 
-We can write points too, assuming we have a proxy. You can't write points
-directly via the API. Unlike all other classes, this one requires the proxy
-address and port as its credential hash.
+We can write points too, assuming we have access to a proxy, because
+you can't write points directly via the API. Unlike all other classes, this
+one requires the proxy address and port as its credential hash.
 
 ```ruby
 require 'wavefront-sdk/write'
@@ -77,7 +99,7 @@ wf = Wavefront::Write.new(W_CREDS, debug: true)
 task = wf.write( [{ path: 'dev.test.sdk', value: 10 }])
 
 p task.response
-#<struct sent=1, rejected=0, unsent=0>
+#{"sent"=>1, "rejected"=>0, "unsent"=>0}
 puts task.status.result
 #OK
 ```

data/lib/wavefront-sdk/alert.rb

@@ -5,7 +5,7 @@ module Wavefront
   # View and manage alerts. Alerts are identified by their millisecond
   # epoch timestamp. Returns a Wavefront::Response::Alert object.
   #
-  class Alert < Wavefront::Base
+  class Alert < Base
 
     # GET /api/v2/alert
     # Get all alerts for a customer
@@ -31,7 +31,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/alert/{id}
+    # DELETE /api/v2/alert/id
     # Delete a specific alert.
     #
     # Deleting an active alert moves it to 'trash', from where it can
@@ -46,8 +46,8 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/alert/{id}
-    # GET /api/v2/alert/{id}/history/{version}
+    # GET /api/v2/alert/id
+    # GET /api/v2/alert/id/history/version
     # Get a specific alert / Get a specific historical version of a
     # specific alert.
     #
@@ -63,7 +63,7 @@ module Wavefront
       api_get(fragments.uri_concat)
     end
 
-    # PUT /api/v2/alert/{id}
+    # PUT /api/v2/alert/id
     # Update a specific alert.
     #
     # @param id [String] a Wavefront alert ID
@@ -76,7 +76,7 @@ module Wavefront
       api_put(id, body, 'application/json')
     end
 
-    # GET /api/v2/alert/{id}/history
+    # GET /api/v2/alert/id/history
     # Get the version history of a specific alert.
     #
     # @param id [String] ID of the alert
@@ -87,12 +87,13 @@ module Wavefront
       api_get([id, 'history'].uri_concat)
     end
 
-    # POST /api/v2/alert/{id}/snooze
+    # POST /api/v2/alert/id/snooze
     # Snooze a specific alert for some number of seconds.
     #
     # @param id [String] ID of the alert
-    # @param time [Integer] how many seconds to snooze for. Nil is indefinite
-    # @returns [Hash] object describing the alert with status and
+    # @param seconds [Integer] how many seconds to snooze for.
+    #   Nil is indefinite
+    # @return [Hash] object describing the alert with status and
     #   response keys
     #
     def snooze(id, seconds = nil)
@@ -101,11 +102,11 @@ module Wavefront
       api_post([id, "snooze#{qs}"].uri_concat, nil)
     end
 
-    # GET /api/v2/alert/{id}/tag
+    # GET /api/v2/alert/id/tag
     # Get all tags associated with a specific alert.
     #
     # @param id [String] ID of the alert
-    # @returns [Hash] object describing the alert with status and
+    # @return [Hash] object describing the alert with status and
     #   response keys
     #
     def tags(id)
@@ -113,12 +114,12 @@ module Wavefront
       api_get([id, 'tag'].uri_concat)
     end
 
-    # POST /api/v2/alert/{id}/tag
+    # POST /api/v2/alert/id/tag
     # Set all tags associated with a specific alert.
     #
     # @param id [String] ID of the alert
     # @param tags [Array] list of tags to set.
-    # @returns [Hash] object describing the alert with status and
+    # @return [Hash] object describing the alert with status and
     #   response keys
     #
     def tag_set(id, tags)
@@ -128,12 +129,12 @@ module Wavefront
       api_post([id, 'tag'].uri_concat, tags.to_json, 'application/json')
     end
 
-    # DELETE /api/v2/alert/{id}/tag/{tagValue}
+    # DELETE /api/v2/alert/id/tag/tagValue
     # Remove a tag from a specific alert.
     #
     # @param id [String] ID of the alert
     # @param tag [String] tag to delete
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_delete(id, tag)
       wf_alert_id?(id)
@@ -141,12 +142,12 @@ module Wavefront
       api_delete([id, 'tag', tag].uri_concat)
     end
 
-    # PUT /api/v2/alert/{id}/tag/{tagValue}
+    # PUT /api/v2/alert/id/tag/tagValue
     # Add a tag to a specific alert.
     #
     # @param id [String] ID of the alert
     # @param tag [String] tag to set.
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_add(id, tag)
       wf_alert_id?(id)
@@ -154,7 +155,7 @@ module Wavefront
       api_put([id, 'tag', tag].uri_concat)
     end
 
-    # POST /api/v2/alert/{id}/undelete
+    # POST /api/v2/alert/id/undelete
     # Undelete a specific alert.
     #
     # @param id [String] ID of the alert
@@ -165,11 +166,11 @@ module Wavefront
       api_post([id, 'undelete'].uri_concat)
     end
 
-    # POST /api/v2/alert/{id}/unsnooze
+    # POST /api/v2/alert/id/unsnooze
     # Unsnooze a specific alert.
     #
     # @param id [String] ID of the alert
-    # @returns [Hash] object describing the alert with status and
+    # @return [Hash] object describing the alert with status and
     #   response keys
     #
     def unsnooze(id)
@@ -186,10 +187,4 @@ module Wavefront
       api_get('summary')
     end
   end
-
-  # A standard response
-  #
-  class Response
-    class Alert < Base; end
-  end
 end

data/lib/wavefront-sdk/base.rb

@@ -3,6 +3,7 @@ require 'time'
 require 'faraday'
 require 'pp'
 require 'ostruct'
+require 'addressable'
 require_relative './exception'
 require_relative './mixins'
 require_relative './response'
@@ -15,8 +16,7 @@ module Wavefront
   # any call to the Wavefront API from this SDK, you are returned an
   # OpenStruct object.
   #
-  # @returns a Wavefront::Class::Response object where Class matches
-  # the inheriting class name.
+  # @return a Wavefront::Response object
   #
   class Base
     include Wavefront::Validators
@@ -85,8 +85,8 @@ module Wavefront
     #
     def mk_conn(path, headers = {})
       Faraday.new(
-        url:     "https://#{net[:endpoint]}" +
-                 [net[:api_base], path].uri_concat,
+        url:     Addressable::URI.encode("https://#{net[:endpoint]}" +
+                 [net[:api_base], path].uri_concat),
         headers: net[:headers].merge(headers)
       )
     end
@@ -98,7 +98,8 @@ module Wavefront
     #
     # @param path [String] path to be appended to the
     #   #net[:api_base] path.
-    # @param qs [String] optional query string
+    # @param query [Hash] optional key-value pairs with will be made
+    #   into aquery string
     # @return [Hash] API response
     #
     def api_get(path, query = {})
@@ -154,11 +155,12 @@ module Wavefront
     end
 
     # doing a PUT to update an object requires only a certain subset of
-    # the keys returned by #describe().
+    # the keys returned by #describe(). This method takes the
+    # existing description of an object and turns it into a new has
+    # which can be PUT.
     #
-    # @param body [Hash] a hash of the existing object merged with the
-    #   hash describing the user's change(s).
-    # @param keys [Array, String] the keys(s) the user wishes to update
+    # @param old [Hash] a hash of the existing object
+    # @param new [Hash] the keys you wish to update
     # @return [Hash] a hash containing only the keys which need to be
     #   sent to the API. Keys will be symbolized.
     #
@@ -187,13 +189,20 @@ module Wavefront
         #
         return if level == :debug && ! opts[:debug]
         return if level == :info && ! opts[:verbose]
-
         puts msg
       end
     end
 
+    # If we need to massage a raw response to fit what the
+    # Wavefront::Response class expects (I'm looking at you,
+    # 'User'), a class can provide a {#response_shim} method.
+    #
     def respond(resp)
-      response_class.send(:new, resp.body, resp.status || {})
+      body = respond_to?(:response_shim) ? response_shim(resp.body,
+                                                         resp.status) :
+                                           resp.body
+
+      Wavefront::Response.new(body, resp.status)
     end
 
     private
@@ -226,11 +235,6 @@ module Wavefront
       respond(resp)
     end
 
-    def response_class
-       Object.const_get(
-        "Wavefront::Response::#{self.class.name.split('::').last}")
-    end
-
     def setup_endpoint(creds)
       %w(endpoint token).each do |k|
         raise "creds must contain #{k}" unless creds.key?(k.to_sym)

data/lib/wavefront-sdk/cloudintegration.rb

@@ -5,7 +5,7 @@ module Wavefront
   # View and manage Cloud Integrations. These are identified by
   # a UUID.
   #
-  class CloudIntegration < Wavefront::Base
+  class CloudIntegration < Base
 
     # GET /api/v2/cloudintegration
     # Get all cloud integrations for a customer
@@ -30,7 +30,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/cloudintegration/{id}
+    # DELETE /api/v2/cloudintegration/id
     # Delete a specific cloud integration
     #
     # Deleting an active integration moves it to 'trash', from where
@@ -45,7 +45,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/cloudintegration/{id}
+    # GET /api/v2/cloudintegration/id
     # Get a specific cloud integration
     #
     # @param id [String] ID of the integration
@@ -56,7 +56,7 @@ module Wavefront
       api_get(id)
     end
 
-    # PUT /api/v2/cloudintegration/{id}
+    # PUT /api/v2/cloudintegration/id
     # Update a specific cloud integration
     #
     # @param id [String] ID of the integration
@@ -68,7 +68,7 @@ module Wavefront
       api_put(id, body)
     end
 
-    # POST /api/v2/cloudintegration/{id}/undelete
+    # POST /api/v2/cloudintegration/id/undelete
     # Undelete a specific cloud integration
     #
     # @param id [String] ID of the integration
@@ -79,10 +79,4 @@ module Wavefront
       api_post([id, 'undelete'].uri_concat)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class CloudIntegration < Base; end
-  end
 end

data/lib/wavefront-sdk/credentials.rb

@@ -1,9 +1,19 @@
 require 'pathname'
 require 'inifile'
+require 'map'
 
 module Wavefront
 
-  # Helper methods to get Wavefront credentials
+  # Helper methods to get Wavefront credentials.
+  #
+  # @return [Wavefront::Credentials]
+  #
+  # @!attribute config [r]
+  #   @return [Map] the entire loaded config
+  # @!attribute creds [r]
+  #   @return [Map] credentials for speaking to the Wavefront API
+  # @!attribute proxy [r]
+  #   @return [Map] information for speaking to a Wavefront proxy
   #
   class Credentials
     attr_reader :opts, :config, :creds, :proxy
@@ -35,9 +45,9 @@ module Wavefront
     end
 
     def populate(raw)
-      @config = raw
-      @creds = raw.select { |k, _v| [:endpoint, :token].include?(k) }
-      @proxy = raw.select { |k, _v| [:proxy, :port].include?(k) }
+      @config = Map(raw)
+      @creds = Map(raw.select { |k, _v| [:endpoint, :token].include?(k) })
+      @proxy = Map(raw.select { |k, _v| [:proxy, :port].include?(k) })
     end
 
     def load_from_file(opts)

data/lib/wavefront-sdk/dashboard.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # View and manage dashboards.
   #
-  class Dashboard < Wavefront::Base
+  class Dashboard < Base
 
     # GET /api/v2/dashboard
     # Get all dashboards for a customer.
@@ -29,7 +29,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/dashboard/{id}
+    # DELETE /api/v2/dashboard/id
     # Delete a specific dashboard.
     # Deleting an active dashboard moves it to 'trash', from where it can
     # be restored with an #undelete operation. Deleting an dashboard in
@@ -43,7 +43,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/dashboard/{id}
+    # GET /api/v2/dashboard/id
     # Get a specific dashboard / Get a specific historical version of a
     # specific dashboard.
     #
@@ -59,7 +59,7 @@ module Wavefront
       api_get(fragments.uri_concat)
     end
 
-    # PUT /api/v2/dashboard/{id}
+    # PUT /api/v2/dashboard/id
     # Update a specific dashboard.
     #
     # Refer to the Swagger API docs for valid keys.
@@ -73,7 +73,7 @@ module Wavefront
       api_put(id, body)
     end
 
-    # GET /api/v2/dashboard/{id}/history
+    # GET /api/v2/dashboard/id/history
     # Get the version history of an dashboard.
     #
     # @param id [String] ID of the dashboard
@@ -84,11 +84,11 @@ module Wavefront
       api_get([id, 'history'].uri_concat)
     end
 
-    # GET /api/v2/dashboard/{id}/tag
+    # GET /api/v2/dashboard/id/tag
     # Get all tags associated with a specific dashboard.
     #
     # @param id [String] ID of the dashboard
-    # @returns [Hash] object describing the dashboard with status and
+    # @return [Hash] object describing the dashboard with status and
     #   response keys
     #
     def tags(id)
@@ -96,12 +96,12 @@ module Wavefront
       api_get([id, 'tag'].uri_concat)
     end
 
-    # POST /api/v2/dashboard/{id}/tag
+    # POST /api/v2/dashboard/id/tag
     # Set all tags associated with a specific dashboard.
     #
     # @param id [String] ID of the dashboard
     # @param tags [Array] list of tags to set.
-    # @returns [Hash] object describing the dashboard with status and
+    # @return [Hash] object describing the dashboard with status and
     #   response keys
     #
     def tag_set(id, tags)
@@ -111,12 +111,12 @@ module Wavefront
       api_post([id, 'tag'].uri_concat, tags.to_json, 'application/json')
     end
 
-    # DELETE /api/v2/dashboard/{id}/tag/{tagValue}
+    # DELETE /api/v2/dashboard/id/tag/tagValue
     # Remove a tag from a specific dashboard.
     #
     # @param id [String] ID of the dashboard
     # @param tag [String] tag to delete
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_delete(id, tag)
       wf_dashboard_id?(id)
@@ -124,12 +124,12 @@ module Wavefront
       api_delete([id, 'tag', tag].uri_concat)
     end
 
-    # PUT /api/v2/dashboard/{id}/tag/{tagValue}
+    # PUT /api/v2/dashboard/id/tag/tagValue
     # Add a tag to a specific dashboard.
     #
     # @param id [String] ID of the dashboard
     # @param tag [String] tag to set.
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_add(id, tag)
       wf_dashboard_id?(id)
@@ -137,7 +137,7 @@ module Wavefront
       api_put([id, 'tag', tag].uri_concat)
     end
 
-    # POST /api/v2/dashboard/{id}/undelete
+    # POST /api/v2/dashboard/id/undelete
     # Move an dashboard from 'trash' back into active service.
     #
     # @param id [String] ID of the dashboard
@@ -148,10 +148,4 @@ module Wavefront
       api_post([id, 'undelete'].uri_concat)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class Dashboard < Base; end
-  end
 end