m2x 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ec355421314977e15e2c05ae0eb1efc9d0177d4
-  data.tar.gz: ed401f222ce4c00a41e2d347a1fcafb268a2d433
+  metadata.gz: 084cf856cdc4b7844875f78adb56260dc52257a0
+  data.tar.gz: b9cc0d3d5185bc385d37121fa183248ceaef97f4
 SHA512:
-  metadata.gz: f1e7b7bac788b62e4868e16073d048bb104e64984c1fbe08df3d1e47fccd2b01482a10f67b096b7dacfa9e37644a6031ec3d1750af88eda41e61d273d5289815
-  data.tar.gz: cdde61bc4b9f577c5d9bbaf85f6ebfd079f158c3bbbc75e8caeb9305837d536d4e9ada1715100332d59dcafd87ca8e59c82f7cd90bebd20d7e3f40f1c521c658
+  metadata.gz: 33ee0afd354825adbe05a148c191776e07dd1ac3c3d41fb220d90fc1eee6f7d8040baa5f3cee0106fdb5961e977a149d5ae14600a8db5196552045cef03a898d
+  data.tar.gz: 1f12c23f3fe2aea2ccf4ccb93797c4be1a7b08b6fe336ba7a157b1c92a45d0db98d5007cd1ff3da17f527e10412388dffd54b6626048e421d0b9d99754c22fd1

data/README.md

@@ -9,7 +9,7 @@ Getting Started
 ==========================
 1. Signup for an [M2X Account](https://m2x.att.com/signup).
 2. Obtain your _Master Key_ from the Master Keys tab of your [Account Settings](https://m2x.att.com/account) screen.
-2. Create your first [Data Source Blueprint](https://m2x.att.com/blueprints) and copy its _Feed ID_.
+2. Create your first [Device](https://m2x.att.com/devices) and copy its _Device ID_.
 3. Review the [M2X API Documentation](https://m2x.att.com/developer/documentation/overview).
 
 ## Installation
@@ -20,43 +20,46 @@ $ gem install m2x
 
 ## Usage
 
-In order to communicate with the M2X API, you need an instance of [M2X](lib/m2x.rb). You need to pass your API key in the constructor to access your data.
+In order to communicate with the M2X API, you need an instance of [M2X::Client](lib/m2x/client.rb). You need to pass your API key in the constructor to access your data.
 
 ```ruby
-m2x = M2X.new(<YOUR-API-KEY>)
+m2x = M2X::Client.new(<YOUR-API-KEY>)
 ```
 
 This provides an interface to your data on M2X
 
-- [Blueprints](lib/m2x/blueprints.rb)
+- [Distribution](lib/m2x/distribution.rb)
   ```ruby
-  blueprints_api = m2x.blueprints
-  ```
+  distribution = m2x.distribution("<DISTRIBUTION-ID>")
 
-- [Batches](lib/m2x/batches.rb)
-  ```ruby
-  batches_api = m2x.batches
-  ```
-- [Datasources](lib/m2x/datasources.rb)
-  ```ruby
-  datasources_api = m2x.datasources
+  distributions = m2x.distributions
   ```
 
-- [Feeds](lib/m2x/feeds.rb)
+- [Device](lib/m2x/device.rb)
   ```ruby
-  feeds_api = m2x.feeds
+  device = m2x.device("<DEVICE-ID>")
+
+  devices = m2x.devices
   ```
 
-- [Keys](lib/m2x/keys.rb)
+- [Key](lib/m2x/key.rb)
   ```ruby
-  keys_api = m2x.keys
+  key = m2x.key("<KEY-TOKEN>")
+
+  keys = m2x.keys
   ```
 
 Refer to the documentation on each class for further usage instructions.
 
 ## Example
 
-In order to run this example, you will need a `Feed ID` and `API Key`. If you don't have any, access your M2X account, create a new [Data Source Blueprint](https://m2x.att.com/blueprints), and copy the `Feed ID` and `API Key` values. The following script will send your CPU load average to three different streams named `load_1m`, `load_5m` and `load_15`. Check that there's no need to create a stream in order to write values into it:
+In order to run this example, you will need a `Device ID` and `API Key`. If you don't have any, access your M2X account, create a new [Device](https://m2x.att.com/devices), and copy the `Device ID` and `API Key` values. The following script will send your CPU load average to three different streams named `load_1m`, `load_5m` and `load_15`. Check that there's no need to create a stream in order to write values into it.
+
+In order to execute this script run:
+
+```bash
+API_KEY=<YOUR-API-KEY> DEVICE=<YOUR-DEVICE-ID> ./m2x-uptime.rb
+```
 
 ```ruby
 #! /usr/bin/env ruby
@@ -69,13 +72,17 @@ In order to run this example, you will need a `Feed ID` and `API Key`. If you do
 require "time"
 require "m2x"
 
-API_KEY = "<YOUR-FEED-API-KEY>"
-FEED    = "<YOUR-FEED-ID>"
+API_KEY = ENV.fetch("API_KEY")
+DEVICE  = ENV.fetch("DEVICE")
 
-m2x = M2X.new(API_KEY)
+puts "M2X::Client/#{M2X::Client::VERSION} example"
 
 @run = true
-trap(:INT) { @run = false }
+
+stop = Proc.new { @run = false }
+
+trap(:INT,  &stop)
+trap(:TERM, &stop)
 
 # Match `uptime` load averages output for both Linux and OSX
 UPTIME_RE = /(\d+\.\d+),? (\d+\.\d+),? (\d+\.\d+)$/
@@ -84,10 +91,15 @@ def load_avg
   `uptime`.match(UPTIME_RE).captures
 end
 
+m2x = M2X::Client.new(API_KEY)
+
+# Get the device
+device = m2x.device(DEVICE)
+
 # Create the streams if they don't exist
-m2x.feeds.update_stream(FEED, "load_1m")
-m2x.feeds.update_stream(FEED, "load_5m")
-m2x.feeds.update_stream(FEED, "load_15m")
+device.create_stream("load_1m")
+device.create_stream("load_5m")
+device.create_stream("load_15m")
 
 while @run
   load_1m, load_5m, load_15m = load_avg
@@ -96,14 +108,14 @@ while @run
   now = Time.now.iso8601
 
   values = {
-    load_1m:  [ { value: load_1m, at: now } ],
-    load_5m:  [ { value: load_5m, at: now } ],
-    load_15m: [ { value: load_15m, at: now } ]
+    load_1m:  [ { value: load_1m,  timestamp: now } ],
+    load_5m:  [ { value: load_5m,  timestamp: now } ],
+    load_15m: [ { value: load_15m, timestamp: now } ]
   }
 
-  res = m2x.feeds.post_multiple(FEED, values)
+  res = device.post_updates(values: values)
 
-  abort res.json["message"] unless res.code == 202
+  abort res.json["message"] unless res.success?
 
   sleep 1
 end

data/lib/m2x/client.rb

@@ -2,94 +2,180 @@ require "net/http"
 require "json"
 require "openssl"
 
-class M2X
-  class Client
-    API_BASE = "http://api-m2x.att.com/v1".freeze
+# Interface for connecting with M2X API service.
+#
+# This class provides convenience methods to access M2X most common resources.
+# It can also be used to access any endpoint directly like this:
+#
+#     m2x = M2X::Client.new("<YOUR-API-KEY>")
+#     m2x.get("/some_path")
+#
+class M2X::Client
+  DEFAULT_API_BASE    = "https://api-m2x.att.com".freeze
+  DEFAULT_API_VERSION = "v2".freeze
+
+  CA_FILE = File.expand_path("../cacert.pem", __FILE__)
+
+  USER_AGENT = "M2X-Ruby/#{M2X::Client::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION} (#{RUBY_PLATFORM})".freeze
+
+  attr_accessor :api_key
+  attr_accessor :api_base
+  attr_accessor :api_version
+  attr_reader   :last_response
+
+  def initialize(api_key=nil, api_base=nil)
+    @api_key     = api_key
+    @api_base    = api_base
+    @api_version = api_version
+  end
 
-    CA_FILE = File.expand_path("../cacert.pem", __FILE__)
+  # Returns the status of the M2X system.
+  #
+  # The response to this endpoint is an object in which each of its attributes
+  # represents an M2X subsystem and its current status.
+  def status
+    get("/status")
+  end
 
-    USER_AGENT = "M2X/#{::M2X::VERSION} (Ruby Net::HTTP)".freeze
+  # Obtain a Device from M2X
+  #
+  # This method instantiates an instance of Device and calls `Device#view`
+  # method, returning the device instance with all its attributes initialized
+  def device(id)
+    M2X::Client::Device.new(self, "id" => id).tap(&:view)
+  end
 
-    def initialize(api_key=nil, api_base=nil)
-      @api_base = api_base
-      @api_key  = api_key
-    end
+  # Creates a new device on M2X with the specified parameters
+  def create_device(params)
+    M2X::Client::Device.create!(self, params)
+  end
 
-    def request(verb, path, qs=nil, params=nil, headers=nil)
-      url = URI.parse(File.join(api_base, path))
+  # Retrieve the list of devices accessible by the authenticated API key that
+  # meet the search criteria.
+  #
+  # See M2X::Client::Device.list for more details
+  def devices(params={})
+    M2X::Client::Device.list(self, params)
+  end
 
-      url.query = URI.encode_www_form(qs) unless qs.nil? || qs.empty?
+  # Search the catalog of public Devices.
+  #
+  # This allows unauthenticated users to search Devices from other users that
+  # have been marked as public, allowing them to read public Device metadata,
+  # locations, streams list, and view each Devices' stream metadata and its
+  # values.
+  #
+  # See M2X::Client::Device.catalog for more details
+  def device_catalog(params={})
+    M2X::Client::Device.catalog(self, params)
+  end
 
-      headers = default_headers.merge(headers || {})
+  # Obtain a Distribution from M2X
+  #
+  # This method instantiates an instance of Distribution and calls
+  # `Distribution#view` method, returning the device instance with all
+  # its attributes initialized
+  def distribution(id)
+    M2X::Client::Distribution.new(self, "id" => id).tap(&:view)
+  end
 
-      body = if params
-               headers["Content-Type"] ||= "application/x-www-form-urlencoded"
+  # Creates a new device distribution on M2X with the specified parameters
+  def create_distribution(params)
+    M2X::Client::Distribution.create!(self, params)
+  end
 
-               case headers["Content-Type"]
-               when "application/json" then JSON.dump(params)
-               when "application/x-www-form-urlencoded" then URI.encode_www_form(params)
-               else
-                 raise ArgumentError, "Unrecognized Content-Type `#{headers["Content-Type"]}`"
-               end
-             end
+  # Retrieve list of device distributions accessible by the authenticated
+  # API key.
+  #
+  # See M2X::Client::Distribution.list for more details
+  def distributions(params={})
+    M2X::Client::Distribution.list(self, params)
+  end
 
-      options = {}
-      options.merge!(use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER, ca_file: CA_FILE) if url.scheme == "https"
+  # Obtain an API Key from M2X
+  #
+  # This method instantiates an instance of Key and calls
+  # `Key#view` method, returning the key instance with all
+  # its attributes initialized
+  def key(key)
+    M2X::Client::Key.new(self, "key" => key).tap(&:view)
+  end
 
-      path = url.path
-      path << "?#{url.query}" if url.query
+  # Create a new API Key
+  #
+  # Note that, according to the parameters sent, you can create a
+  # Master API Key or a Device/Stream API Key.
+  #
+  # See M2X::Client::Key.create! for more details
+  def create_key(params)
+    M2X::Client::Key.create!(self, params)
+  end
 
-      res = Net::HTTP.start(url.host, url.port, options) do |http|
-        http.send_request(verb.to_s.upcase, path, body, headers)
-      end
+  # Retrieve list of keys associated with the user account.
+  #
+  # See M2X::Client::Key.list for more details
+  def keys
+    M2X::Client::Key.list(self)
+  end
 
-      Response.new(res)
+  # Define methods for accessing M2X REST API
+  [:get, :post, :put, :delete, :head, :options, :patch].each do |verb|
+    define_method verb do |path, qs=nil, params=nil, headers=nil|
+      request(verb, path, qs, params, headers)
     end
+  end
 
-    [:get, :post, :put, :delete, :head, :options, :patch].each do |verb|
-      define_method verb do |path, qs=nil, params=nil, headers=nil|
-        request(verb, path, qs, params, headers)
-      end
-    end
+  private
+  def request(verb, path, qs=nil, params=nil, headers=nil)
+    url = URI.parse(File.join(api_base, versioned(path)))
 
-    class Response
-      attr_reader :response
+    url.query = URI.encode_www_form(qs) unless qs.nil? || qs.empty?
 
-      def initialize(response)
-        @response = response
-      end
+    headers = default_headers.merge(headers || {})
 
-      def raw
-        @response.body
-      end
+    body = if params
+             headers["Content-Type"] ||= "application/x-www-form-urlencoded"
 
-      def json
-        raise "#{@response.content_type} is not application/json" unless @response.content_type == "application/json"
+             case headers["Content-Type"]
+             when "application/json" then JSON.dump(params)
+             when "application/x-www-form-urlencoded" then URI.encode_www_form(params)
+             else
+               raise ArgumentError, "Unrecognized Content-Type `#{headers["Content-Type"]}`"
+             end
+           end
 
-        @json ||= ::JSON.parse(raw)
-      end
+    options = {}
+    options.merge!(use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER, ca_file: CA_FILE) if url.scheme == "https"
 
-      def code
-        @code ||= @response.code.to_i
-      end
+    path = url.path
+    path << "?#{url.query}" if url.query
 
-      def headers
-        @headers ||= @response.to_hash
-      end
+    res = Net::HTTP.start(url.host, url.port, options) do |http|
+      http.send_request(verb.to_s.upcase, path, body, headers)
     end
 
-    private
+    @last_response = Response.new(res)
+  end
 
-    def api_base
-      @api_base ||= API_BASE
-    end
+  def api_base
+    @api_base ||= DEFAULT_API_BASE
+  end
 
-    def default_headers
-      @headers ||= begin
-                     headers = { "User-Agent" => USER_AGENT }
-                     headers.merge!("X-M2X-KEY" => @api_key) if @api_key
-                     headers
-                   end
-    end
+  def api_version
+    @api_version ||= DEFAULT_API_VERSION
+  end
+
+  def versioned(path)
+    versioned?(path) ? path : "/#{api_version}#{path}"
+  end
+
+  def versioned?(path)
+    path =~ /^\/v\d+\//
+  end
+
+  def default_headers
+    @headers ||= { "User-Agent" => USER_AGENT }.tap do |headers|
+                   headers["X-M2X-KEY"] = @api_key if @api_key
+                 end
   end
 end

data/lib/m2x/device.rb

@@ -0,0 +1,147 @@
+# Wrapper for AT&T M2X Device API
+# https://m2x.att.com/developer/documentation/v2/device
+class M2X::Client::Device < M2X::Client::Resource
+
+  PATH = "/devices"
+
+  class << self
+    # Retrieve the list of devices accessible by the authenticated API key that
+    # meet the search criteria.
+    #
+    # https://m2x.att.com/developer/documentation/v2/device#List-Search-Devices
+    def list(client, params={})
+      res = client.get(PATH, params)
+
+      res.json["devices"].map{ |atts| new(client, atts) } if res.success?
+    end
+
+    # Search the catalog of public Devices.
+    #
+    # This allows unauthenticated users to search Devices from other users
+    # that have been marked as public, allowing them to read public Device
+    # metadata, locations, streams list, and view each Devices' stream metadata
+    # and its values.
+    #
+    # https://m2x.att.com/developer/documentation/v2/device#List-Search-Public-Devices-Catalog
+    def catalog(client, params={})
+      res = client.get("#{PATH}/catalog", params)
+
+      res.json["devices"].map{ |atts| new(client, atts) } if res.success?
+    end
+
+    # List Device Groups
+    # Retrieve the list of device groups for the authenticated user.
+    #
+    # https://m2x.att.com/developer/documentation/v2/device#List-Device-Groups
+    def groups(client)
+      client.get("#{PATH}/groups")
+    end
+
+    # Create a new device
+    #
+    # https://m2x.att.com/developer/documentation/v2/device#Create-Device
+    def create!(client, params)
+      res = client.post(PATH, nil, params, "Content-Type" => "application/json")
+
+      new(client, res.json) if res.success?
+    end
+  end
+
+  def path
+    @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
+  end
+
+  # View Request Log
+  # Retrieve list of HTTP requests received lately by the specified device
+  # (up to 100 entries).
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#View-Request-Log
+  def log
+    @client.get("#{path}/log")
+  end
+
+  # Get location details of an existing Device.
+  #
+  # Note that this method can return an empty value (response status
+  # of 204) if the device has no location defined.
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location
+  def location
+    @client.get("#{path}/location")
+  end
+
+  # Update the current location of the specified device.
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Update-Device-Location
+  def update_location(params)
+    @client.put("#{path}/location", nil, params, "Content-Type" => "application/json")
+  end
+
+  # Post Device Updates (Multiple Values to Multiple Streams)
+  #
+  # This method allows posting multiple values to multiple streams
+  # belonging to a device and optionally, the device location.
+  #
+  # All the streams should be created before posting values using this method.
+  #
+  # The `values` parameter contains an object with one attribute per each stream to be updated.
+  # The value of each one of these attributes is an array of timestamped values.
+  #
+  #      {
+  #         temperature: [
+  #                        { "timestamp": <Time in ISO8601>, "value": x },
+  #                        { "timestamp": <Time in ISO8601>, "value": y },
+  #                      ],
+  #         humidity:    [
+  #                        { "timestamp": <Time in ISO8601>, "value": x },
+  #                        { "timestamp": <Time in ISO8601>, "value": y },
+  #                      ]
+  #
+  #      }
+  #
+  # The optional location attribute can contain location information that will
+  # be used to update the current location of the specified device
+  #
+  # https://staging.m2x.sl.attcompute.com/developer/documentation/v2/device#Post-Device-Updates--Multiple-Values-to-Multiple-Streams-
+  def post_updates(params)
+    @client.post("#{path}/updates", nil, params, "Content-Type" => "application/json")
+  end
+
+  # Retrieve list of data streams associated with the device.
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#List-Data-Streams
+  def streams
+    ::M2X::Client::Stream.list(@client, self)
+  end
+
+  # Get details of a specific data Stream associated with the device
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#View-Data-Stream
+  def stream(name)
+    ::M2X::Client::Stream.fetch(@client, self, name)
+  end
+
+  # Update a data stream associated with the Device
+  # (if a stream with this name does not exist it gets created).
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream
+  def update_stream(name, params={})
+    stream = ::M2X::Client::Stream.new(@client, self, "name" => name)
+
+    stream.update!(params)
+  end
+  alias_method :create_stream, :update_stream
+
+  # Returns a list of API keys associated with the device
+  def keys
+    ::M2X::Client::Key.list(@client, params.merge(device: self["id"]))
+  end
+
+  # Creates a new API key associated to the device
+  #
+  # If a parameter named `stream` is supplied with a stream name, it
+  # will create an API key associated with that stream only.
+  def create_key(params)
+    ::M2X::Client::Key.create!(@client, params.merge(device: self["id"]))
+  end
+end

data/lib/m2x/distribution.rb

@@ -0,0 +1,53 @@
+# Wrapper for AT&T M2X Distribution API
+# https://m2x.att.com/developer/documentation/v2/distribution
+class M2X::Client::Distribution < M2X::Client::Resource
+
+  PATH = "/distributions"
+
+  class << self
+    # Retrieve list of device distributions accessible by the authenticated
+    # API key.
+    #
+    # https://m2x.att.com/developer/documentation/v2/distribution#List-Distributions
+    def list(client, params={})
+      res = client.get(PATH, params)
+
+      res.json["distributions"].map{ |atts| new(client, atts) } if res.success?
+    end
+    alias_method :search, :list
+
+    # Create a new device distribution
+    #
+    # https://m2x.att.com/developer/documentation/v2/distribution#Create-Distribution
+    def create!(client, params)
+      res = client.post(PATH, nil, params, "Content-Type" => "application/json")
+
+      new(client, res.json) if res.success?
+    end
+  end
+
+  def path
+    @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
+  end
+
+  # Retrieve list of devices added to the specified distribution.
+  #
+  # https://m2x.att.com/developer/documentation/v2/distribution#List-Devices-from-an-existing-Distribution
+  def devices(params={})
+    res = @client.get("#{path}/devices", params)
+
+    res.json["devices"].map{ |atts| ::M2X::Client::Device.new(@client, atts) } if res.success?
+  end
+
+  # Add a new device to an existing distribution
+  #
+  # Accepts a `serial` parameter, that must be a unique identifier
+  # within this distribution.
+  #
+  # https://m2x.att.com/developer/documentation/v2/distribution#Add-Device-to-an-existing-Distribution
+  def add_device(serial)
+    res = @client.post("#{path}/devices", nil, { serial: serial }, "Content-Type" => "application/json")
+
+    ::M2X::Client::Device.new(@client, res.json) if res.success?
+  end
+end

data/lib/m2x/key.rb

@@ -0,0 +1,49 @@
+# Wrapper for AT&T M2X Keys API
+# https://m2x.att.com/developer/documentation/v2/keys
+class M2X::Client::Key < M2X::Client::Resource
+
+  PATH = "/keys"
+
+  class << self
+    # Retrieve list of keys associated with the user account.
+    #
+    # https://m2x.att.com/developer/documentation/v2/keys#List-Keys
+    def list(client, params={})
+      res = client.get(PATH, params)
+
+      res.json["keys"].map{ |atts| new(client, atts) } if res.success?
+    end
+
+    # Create a new API Key
+    #
+    # Note that, according to the parameters sent, you can create a
+    # Master API Key or a Device/Stream API Key.
+    #
+    # https://m2x.att.com/developer/documentation/v2/keys#Create-Key
+    def create!(client, params={})
+      res = client.post(PATH, nil, params, "Content-Type" => "application/json")
+
+      new(client, res.json) if res.success?
+    end
+  end
+
+  def path
+    @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("key")) }"
+  end
+
+  # Regenerate an API Key token
+  #
+  # Note that if you regenerate the key that you're using for
+  # authentication then you would need to change your scripts to
+  # start using the new key token for all subsequent requests.
+  #
+  # https://m2x.att.com/developer/documentation/v2/keys#Regenerate-Key
+  def regenerate
+    res = @client.post("#{path}/regenerate", nil, {})
+
+    if res.success?
+      @path = nil
+      @attributes = res.json
+    end
+  end
+end

data/lib/m2x/resource.rb

@@ -0,0 +1,40 @@
+require "forwardable"
+
+# Wrapper for M2X::Client resources
+class M2X::Client::Resource
+  extend Forwardable
+
+  attr_reader :attributes
+
+  def_delegator :@attributes, :[]
+
+  def initialize(client, attributes)
+    @client     = client
+    @attributes = attributes
+  end
+
+  # Return the resource details
+  def view
+    res = @client.get(path)
+
+    @attributes = res.json if res.success?
+  end
+
+  # Update an existing resource details
+  def update!(params)
+    @client.put(path, nil, params, "Content-Type" => "application/json")
+  end
+
+  # Delete the resource
+  def delete!
+    @client.delete(path)
+  end
+
+  def inspect
+    "<#{self.class.name}: #{attributes.inspect}>"
+  end
+
+  def path
+    raise NotImplementedError
+  end
+end