m2x 0.0.1

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Leandro López and Matías Flores
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# AT&T's M2X Ruby Client
+
+[AT&T’s M2X](https://m2x.att.com/) is a cloud-based fully managed data storage service for network connected machine-to-machine (M2M) devices. From trucks and turbines to vending machines and freight containers, M2X enables the devices that power your business to connect and share valuable data.
+
+This gem aims to provide a simple wrapper to interact with [AT&T M2X API](https://m2x.att.com/developer/documentation/overview). Refer to the [Glossary of Terms](https://m2x.att.com/developer/documentation/glossary) to understand the nomenclature used through this documentation.
+
+## Example Usage
+
+In order to be able to use this gem you will need an [AT&T M2X](https://m2x.att.com/) API key and a Data Source ID. If you don't have an API key, create an account and, once registered and with your account activated, 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:
+
+    #! /usr/bin/env ruby
+
+    #
+    # See https://github.com/attm2x/m2x-ruby/blob/master/README.md#example-usage
+    # for instructions
+    #
+
+    require "m2x"
+
+    API_KEY = "<YOUR-FEED-API-KEY>"
+    FEED    = "<YOUR-FEED-ID>"
+
+    m2x = M2X.new(API_KEY)
+
+    @run = true
+    trap(:INT) { @run = false }
+
+    # Match `uptime` load averages output for both Linux and OSX
+    UPTIME_RE = /(\d+\.\d+),? (\d+\.\d+),? (\d+\.\d+)$/
+
+    while @run
+      load_1m, load_5m, load_15m = `uptime`.match(UPTIME_RE).captures
+
+      # Write the different values into AT&T M2X
+      m2x.feeds.update_stream(FEED, "load_1m",  value: load_1m)
+      m2x.feeds.update_stream(FEED, "load_5m",  value: load_5m)
+      m2x.feeds.update_stream(FEED, "load_15m", value: load_15m)
+
+      sleep 1
+    end
+
+    puts
+
+You can find the script in [`examples/m2x-uptime.rb`](examples/m2x-uptime.rb).
+
+## Versioning
+
+This gem aims to adhere to [Semantic Versioning 2.0.0](http://semver.org/). As a summary, given a version number `MAJOR.MINOR.PATCH`:
+
+1. `MAJOR` will increment when backwards-incompatible changes are introduced to the client.
+2. `MINOR` will increment when backwards-compatible functionality is added.
+3. `PATCH` will increment with backwards-compatible bug fixes.
+
+Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format.
+
+**Note**: the client version does not necessarily reflect the version used in the AT&T M2X API.
+
+## License
+
+This gem is delivered under the MIT license. See [LICENSE](LICENSE) for the terms.

data/lib/m2x.rb

@@ -0,0 +1,31 @@
+require_relative "m2x/client"
+require_relative "m2x/keys"
+require_relative "m2x/feeds"
+
+class M2X
+  VERSION = "0.0.1"
+
+  attr_reader :api_base
+  attr_reader :api_key
+
+  def initialize(api_key=nil, api_base=nil)
+    @api_base = api_base
+    @api_key  = api_key
+  end
+
+  def client
+    @client ||= ::M2X::Client.new(@api_key, @api_base)
+  end
+
+  def status
+    client.get("/status")
+  end
+
+  def keys
+    @keys ||= ::M2X::Keys.new(client)
+  end
+
+  def feeds
+    @feeds ||= ::M2X::Feeds.new(client)
+  end
+end

data/lib/m2x/client.rb

@@ -0,0 +1,97 @@
+require "net/http"
+require "json"
+require "openssl"
+
+class M2X
+  class Client
+    API_BASE = "http://api-m2x.att.com/v1".freeze
+
+    VERSION = "0.0.1".freeze
+
+    CA_FILE = File.expand_path("../cacert.pem", __FILE__)
+
+    USER_AGENT = "M2X/#{VERSION} (Ruby Net::HTTP)".freeze
+
+    def initialize(api_key=nil, api_base=nil)
+      @api_base = api_base
+      @api_key  = api_key
+    end
+
+    def request(verb, path, qs=nil, params=nil, headers=nil)
+      url = URI.parse(File.join(api_base, path))
+
+      url.query = URI.encode_www_form(qs) unless qs.nil? || qs.empty?
+
+      headers = default_headers.merge(headers || {})
+
+      body = if params
+               headers["Content-Type"] ||= "application/x-www-form-urlencoded"
+
+               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
+
+      options = {}
+      options.merge!(use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER, ca_file: CA_FILE) if url.scheme == "https"
+
+      path = url.path
+      path << "?#{url.query}" if url.query
+
+      res = Net::HTTP.start(url.host, url.port, options) do |http|
+        http.send_request(verb.to_s.upcase, path, body, headers)
+      end
+
+      Response.new(res)
+    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
+
+    class Response
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+      end
+
+      def raw
+        @response.body
+      end
+
+      def json
+        raise "#{@response.content_type} is not application/json" unless @response.content_type == "application/json"
+
+        @json ||= ::JSON.parse(raw)
+      end
+
+      def code
+        @code ||= @response.code.to_i
+      end
+
+      def headers
+        @headers ||= @response.to_hash
+      end
+    end
+
+    private
+
+    def api_base
+      @api_base ||= API_BASE
+    end
+
+    def default_headers
+      @headers ||= begin
+                     headers = { "User-Agent" => USER_AGENT }
+                     headers = { "X-M2X-KEY" => @api_key } if @api_key
+                     headers
+                   end
+    end
+  end
+end

data/lib/m2x/feeds.rb

@@ -0,0 +1,90 @@
+class M2X
+
+  # Wrapper for AT&T M2X Feed API
+  #
+  # See https://m2x.att.com/developer/documentation/feed for AT&T M2X
+  # HTTP Feed API documentation.
+  class Feeds
+    # Creates a new M2X Feed API Wrapper
+    def initialize(client)
+      @client = client
+    end
+
+    # List all the feeds that belong to the user associated with the
+    # M2X API key supplied when initializing M2X
+    def list
+      @client.get("/feeds")
+    end
+
+    # Return the details of the supplied feed
+    def view(id)
+      @client.get("/feeds/#{URI.encode(id)}")
+    end
+
+    # Return a list of access log to the supplied feed
+    def log(id)
+      @client.get("/feeds/#{URI.encode(id)}/log")
+    end
+
+    # Return the current location of the supplied feed
+    #
+    # Note that this method can return an empty value (response status
+    # of 204) if the feed has no location defined.
+    def location(id)
+      @client.get("/feeds/#{URI.encode(id)}/location")
+    end
+
+    # Update the current location of the feed
+    def update_location(id, params)
+      @client.put("/feeds/#{URI.encode(id)}/location", nil, params)
+    end
+
+    # Return a list of the associated streams for the supplied feed
+    def streams(id)
+      @client.get("/feeds/#{URI.encode(id)}/streams")
+    end
+
+    # Return a list with the latest values from a stream
+    def stream_values(id, name)
+      @client.get("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/values")
+    end
+
+    # Update stream's properties
+    #
+    # If the stream doesn't exist it will create it. See
+    # https://m2x.att.com/developer/documentation/feed#Create-Update-Data-Stream
+    # for details.
+    def update_stream(id, name, params)
+      @client.put("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}", {}, params)
+    end
+
+    # Delete the stream (and all its values) from the feed
+    def delete_stream(id, name)
+      @client.delete("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}")
+    end
+
+    # Returns a list of API keys associated with the feed
+    def keys(id)
+      @client.get("/keys", feed: id)
+    end
+
+    # Creates a new API key associated to the feed
+    #
+    # 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(id, params)
+      keys_api.create(params.merge(feed: id))
+    end
+
+    # Updates an API key properties
+    def update_key(id, key, params)
+      keys_api.update(key, params.merge(feed: id))
+    end
+
+    private
+
+    def keys_api
+      @keys_api ||= ::M2X::Keys.new(@client)
+    end
+  end
+end

data/lib/m2x/keys.rb

@@ -0,0 +1,59 @@
+class M2X
+
+  # Wrapper for AT&T M2X Keys API
+  #
+  # See https://m2x.att.com/developer/documentation/keys for AT&T M2X
+  # HTTP Keys API documentation.
+  class Keys
+    # Creates a new M2X Keys API wrapper
+    #
+    # See M2X::Client for a description of the client API.
+    def initialize(client)
+      @client = client
+    end
+
+    # List all the Master API Keys that belongs to the user associated
+    # with the AT&T M2X API key supplied when initializing M2X
+    def list
+      @client.get("/keys")
+    end
+
+    # Return the details of the API Key supplied
+    def view(key)
+      @client.get("/keys/#{URI.encode(key.to_s)}")
+    end
+
+    # Delete the supplied API Key
+    def delete(key)
+      @client.delete("/keys/#{URI.encode(key.to_s)}")
+    end
+
+    # Create a new API Key
+    #
+    # Note that, according to the parameters sent, you can create a
+    # Master API Key or a Feed/Stream API Key. See
+    # https://m2x.att.com/developer/documentation/keys#Create-Key for
+    # details on the parameters accepted by this method.
+    def create(params)
+      @client.post("/keys", nil, params, "Content-Type" => "application/json")
+    end
+
+    # Update API Key properties
+    #
+    # This method accepts the same parameters as create API Key and
+    # has the same validations. Note that the Key token cannot be
+    # updated through this method.
+    def update(key, params)
+      @client.put("/keys/#{URI.encode(key.to_s)}", nil, params, "Content-Type" => "application/json")
+    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.
+    def regenerate(key)
+      @client.post("/keys/#{URI.encode(key.to_s)}/regenerate", nil, {})
+    end
+  end
+end

data/m2x.gemspec

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name        = "m2x"
+  s.version     = "0.0.1"
+  s.summary     = "Ruby client for AT&T M2X"
+  s.description = "AT&T’s M2X is a cloud-based fully managed data storage service for network connected machine-to-machine (M2M) devices. From trucks and turbines to vending machines and freight containers, M2X enables the devices that power your business to connect and share valuable data."
+  s.authors     = ["Leandro López", "Matías Flores"]
+  s.email       = ["inkel.ar@gmail.com", "flores.matias@gmail.com"]
+  s.homepage    = "http://github.com/attm2x/m2x-ruby"
+  s.licenses    = ["MIT"]
+
+  s.files = Dir[
+                "LICENSE",
+                "README.md",
+                "lib/**/*.rb",
+                "*.gemspec",
+                "test/*.*"
+               ]
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: m2x
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Leandro López
+- Matías Flores
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-25 00:00:00.000000000 Z
+dependencies: []
+description: AT&T’s M2X is a cloud-based fully managed data storage service for network
+  connected machine-to-machine (M2M) devices. From trucks and turbines to vending
+  machines and freight containers, M2X enables the devices that power your business
+  to connect and share valuable data.
+email:
+- inkel.ar@gmail.com
+- flores.matias@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/m2x/client.rb
+- lib/m2x/feeds.rb
+- lib/m2x/keys.rb
+- lib/m2x.rb
+- m2x.gemspec
+homepage: http://github.com/attm2x/m2x-ruby
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Ruby client for AT&T M2X
+test_files: []