m2x 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 070f2ced4954ff8aacc0fddfa8f978a184f10f10
-  data.tar.gz: 3775ec1a82b2702a458b01d2d316e6985284683c
+  metadata.gz: 8f74e6a48a81266d9c0d7c858bf18fcb3d5d96ea
+  data.tar.gz: 25540ed2233d2319e9cc78df0c26272ebac9f0b3
 SHA512:
-  metadata.gz: e7ff4b69bed09f01ee6c409d620dcc35fd5231c4f386fcd8fd14ee402d8d53d269d19f7c325a51972147c2eae7c5768824fd17063867bb1b68905e6829f907a9
-  data.tar.gz: 9223ce1c387be2808175a35b6280789eb4728bea561bb926ff66b7e8cc3a82385bac4003e77913d73f90be4d2838e70daacd1732d88effc29d707f0e6c3396b2
+  metadata.gz: 88aea446e4d01ae4241e82ef4aeb577e2ac2afd09bcead9605ed7b676eea453c0436732b6c23c017693489e38263515c38780ad2dba9a074d8b23fcc9b0fab49
+  data.tar.gz: 100c2850c65b7cb94c3a20005e8c5ce1968352838710fac14151b573cbc2a1599d45c9d6bf03fabf187d2e0cdc07e9d8e3c64f4b3df56a344c4a7b9766793fe8

data/README.md

@@ -2,7 +2,7 @@
 
 [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.
+This library 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.
 
 
 Getting Started
@@ -12,10 +12,51 @@ Getting Started
 2. Create your first [Data Source Blueprint](https://m2x.att.com/blueprints) and copy its _Feed ID_.
 3. Review the [M2X API Documentation](https://m2x.att.com/developer/documentation/overview).
 
+## Installation
 
-## Example Usage
+```bash
+$ 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.
+
+```ruby
+m2x = M2X.new(<YOUR-API-KEY>)
+```
+
+This provides an interface to your data on M2X
+
+- [Blueprints](lib/m2x/blueprints.rb)
+  ```ruby
+  blueprints_api = m2x.blueprints
+  ```
+
+- [Batches](lib/m2x/batches.rb)
+  ```ruby
+  batches_api = m2x.batches
+  ```
+- [Datasources](lib/m2x/datasources.rb)
+  ```ruby
+  datasources_api = m2x.datasources
+  ```
+
+- [Feeds](lib/m2x/feeds.rb)
+  ```ruby
+  feeds_api = m2x.feeds
+  ```
+
+- [Keys](lib/m2x/keys.rb)
+  ```ruby
+  keys_api = m2x.keys
+  ```
+
+Refer to the documentation on each class for further usage instructions.
+
+## Example
 
-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:
+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:
 
 ```ruby
 #! /usr/bin/env ruby

data/lib/m2x/feeds.rb

@@ -10,20 +10,20 @@ class M2X
       @client = client
     end
 
+    # Search the catalog of public feeds. This allows unauthenticated
+    # users to search feeds from other users that has been marked as
+    # public, allowing only to read their metadata, locations, list
+    # its streams, view each stream metadata and its values.
+    #
+    # Refer to the feed documentation for the full list of supported parameters
+    def catalog(params={})
+      @client.get("/feeds/catalog", params)
+    end
+
     # List/search all the feeds that belong to the user associated
     # with the M2X API key supplied when initializing M2X
     #
-    # The list of feeds can be filtered by using one or more of the
-    # following optional parameters:
-    #
-    # * `q` text to search, matching the name and description.
-    # * `type` one of `bleuprint`, `batch` and `datasource`.
-    # * `tags` a comma separated list of tags.
-    # * `limit` how many results per page.
-    # * `page` the specific results page, starting by 1.
-    # * `latitude` and `longitude` for searching feeds geographically.
-    # * `distance` numeric value in `distance_unit`.
-    # * `distance_unit` either `miles`, `mi` or `km`.
+    # Refer to the feed documentation for the full list of supported parameters
     def list(params={})
       @client.get("/feeds", params)
     end
@@ -62,6 +62,20 @@ class M2X
       @client.get("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}")
     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
+
     # List values from an existing data stream associated with a
     # specific feed, sorted in reverse chronological order (most
     # recent values first).
@@ -80,36 +94,58 @@ class M2X
       @client.get("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/values", params)
     end
 
-    # Update stream's properties
+    # Sample values from an existing data stream associated with a specific
+    # feed, sorted in reverse chronological order (most recent values first).
     #
-    # 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)
+    # This method only works for numeric streams
+    #
+    # Refer to the sampling endpoint documentation for allowed parameters
+    def stream_sampling(id, name, params={})
+      @client.get("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/sampling", 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)}")
+    # Return count, min, max, average and standard deviation stats for the
+    # values on an existing data stream.
+    #
+    # This method only works for numeric streams
+    #
+    # Refer to the stats endpoint documentation for allowed parameters
+    def stream_stats(id, name, params={})
+      @client.get("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/stats", params)
     end
 
-    # Returns a list of API keys associated with the feed
-    def keys(id)
-      @client.get("/keys", feed: id)
+    # Update the current value of the specified stream. The timestamp
+    # is optional. If ommited, the current server time will be used
+    def update_stream_value(id, name, value, timestamp=nil)
+      params = { value: value }
+
+      params[:at] = timestamp if timestamp
+
+      @client.put("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/value", nil, params, "Content-Type" => "application/json")
     end
 
-    # Creates a new API key associated to the feed
+    # Post multiple values to a single stream
     #
-    # 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))
+    # This method allows posting multiple values to a stream
+    # belonging to a feed. The stream should be created before
+    # posting values using this method. The `values` parameter is a
+    # hash with the following format:
+    #
+    #     {
+    #       { "at": <Time in ISO8601>, "value": x },
+    #       { "at": <Time in ISO8601>, "value": y },
+    #       [ ... ]
+    #     }
+    def post_stream_values(id, name, values)
+      params = { values: values }
+      @client.post("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/values", nil, params, "Content-Type" => "application/json")
     end
 
-    # Updates an API key properties
-    def update_key(id, key, params)
-      keys_api.update(key, params.merge(feed: id))
+    # Delete values in a stream by a date range
+    # The `start` and `stop` parameters should be ISO8601 timestamps
+    def delete_stream_values(id, name, start, stop)
+      params = { from: start, end: stop }
+      @client.delete("/feeds/#{URI.encode(id)}/streams/#{URI.encode(name)}/values", nil, params, "Content-Type" => "application/json")
     end
 
     # Post multiple values to multiple streams
@@ -122,18 +158,33 @@ class M2X
     #    {
     #      "stream-name-1": [
     #        { "at": <Time in ISO8601>, "value": x },
-    #        { "value": y }
+    #        { "at": <Time in ISO8601>, "value": y }
     #      ],
     #      "stream-name-2": [ ... ]
     #    }
-    #
-    # If the `at` attribute is missing the the current time of the
-    # server, in UTC, will be used.
     def post_multiple(id, values)
       params = { values: values }
       @client.post("/feeds/#{URI.encode(id)}", nil, params, "Content-Type" => "application/json")
     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

data/lib/m2x/version.rb

@@ -1,3 +1,3 @@
 class M2X
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: m2x
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
 platform: ruby
 authors:
 - Leandro López
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-05 00:00:00.000000000 Z
+date: 2014-10-21 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