class M2X::Client

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")

Constants

CA_FILE
DEFAULT_API_BASE
DEFAULT_API_VERSION
USER_AGENT
VERSION

Attributes

api_base[RW]
api_key[RW]
api_version[RW]
last_response[R]

Public Class Methods

new(api_key=nil, api_base=nil) click to toggle source
# File lib/m2x/client.rb, line 25
def initialize(api_key=nil, api_base=nil)
  @api_key     = api_key
  @api_base    = api_base
  @api_version = api_version
end

Public Instance Methods

collection(id) click to toggle source

Obtain a Collection from M2X

This method instantiates an instance of Collection and calls `Collection#view` method, returning the collection instance with all its attributes initialized

# File lib/m2x/client.rb, line 45
def collection(id)
  M2X::Client::Collection.new(self, "id" => id).tap(&:view)
end
collections(params={}) click to toggle source

Retrieve the list of collections accessible by the authenticated API key

See {M2X::Client::Collection.list} for more details

# File lib/m2x/client.rb, line 59
def collections(params={})
  M2X::Client::Collection.list(self, params)
end
command(id) click to toggle source

View Command Details

This method instantiates an instance of Command and calls `Command#view` method, returning the command instance with all its attributes initialized

# File lib/m2x/client.rb, line 74
def command(id)
  M2X::Client::Command.new(self, "id" => id).tap(&:view)
end
commands(params={}) click to toggle source

List Sent Commands

See {M2X::Client::Command.list} for more details

# File lib/m2x/client.rb, line 66
def commands(params={})
  M2X::Client::Command.list(self, params)
end
create_collection(params) click to toggle source

Creates a new collection on M2X with the specified parameters

See {M2X::Client::Collection.create!} for more details

# File lib/m2x/client.rb, line 52
def create_collection(params)
  M2X::Client::Collection.create!(self, params)
end
create_device(params) click to toggle source

Creates a new device on M2X with the specified parameters

See {M2X::Client::Device.create!} for more details

# File lib/m2x/client.rb, line 96
def create_device(params)
  M2X::Client::Device.create!(self, params)
end
create_distribution(params) click to toggle source

Creates a new device distribution on M2X with the specified parameters

See {M2X::Client::Distribution.create!} for more details.

# File lib/m2x/client.rb, line 139
def create_distribution(params)
  M2X::Client::Distribution.create!(self, params)
end
create_integration(params) click to toggle source

Creates a new integration on M2X with the specified parameters

See {M2X::Client::Integration.create!} for more details

# File lib/m2x/client.rb, line 197
def create_integration(params)
  M2X::Client::Integration.create!(self, params)
end
create_key(params) click to toggle source

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

# File lib/m2x/client.rb, line 174
def create_key(params)
  M2X::Client::Key.create!(self, params)
end
device(id) click to toggle source

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

# File lib/m2x/client.rb, line 89
def device(id)
  M2X::Client::Device.new(self, "id" => id).tap(&:view)
end
device_catalog(params={}) click to toggle source

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

# File lib/m2x/client.rb, line 123
def device_catalog(params={})
  M2X::Client::Device.catalog(self, params)
end
devices(params={}) click to toggle source

Retrieve the list of devices accessible by the authenticated API key

See {M2X::Client::Device.list} for more details

# File lib/m2x/client.rb, line 103
def devices(params={})
  M2X::Client::Device.list(self, params)
end
distribution(id) click to toggle source

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

# File lib/m2x/client.rb, line 132
def distribution(id)
  M2X::Client::Distribution.new(self, "id" => id).tap(&:view)
end
distributions(params={}) click to toggle source

Retrieve list of device distributions accessible by the authenticated API key.

See {M2X::Client::Distribution.list} for more details

# File lib/m2x/client.rb, line 147
def distributions(params={})
  M2X::Client::Distribution.list(self, params)
end
integration(id) click to toggle source

Obtain an Integration from M2X

This method instantiates an instance of Integration and calls `Integration#view` method, returning the integration instance with all its attributes initialized

# File lib/m2x/client.rb, line 190
def integration(id)
  M2X::Client::Integration.new(self, "id" => id).tap(&:view)
end
integrations() click to toggle source

Retrieve list of integrations associated with the user account.

See {M2X::Client::Integration.list} for more details

# File lib/m2x/client.rb, line 204
def integrations
  M2X::Client::Integration.list(self)
end
job(id) click to toggle source

Obtain a Job from M2X

This method instantiates an instance of Job and calls `Job#view` method, returning the job instance with all its attributes initialized

# File lib/m2x/client.rb, line 155
def job(id)
  M2X::Client::Job.new(self, "id" => id).tap(&:view)
end
key(key) click to toggle source

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

# File lib/m2x/client.rb, line 164
def key(key)
  M2X::Client::Key.new(self, "key" => key).tap(&:view)
end
keys() click to toggle source

Retrieve list of keys associated with the user account.

See {M2X::Client::Key.list} for more details

# File lib/m2x/client.rb, line 181
def keys
  M2X::Client::Key.list(self)
end
search_devices(params={}) click to toggle source

Retrieve the list of devices accessible by the authenticated API key that meet the search criteria.

See {M2X::Client::Device.search} for more details

# File lib/m2x/client.rb, line 111
def search_devices(params={})
  M2X::Client::Device.list(self, params)
end
send_command(params) click to toggle source

Send command

See {M2X::Client::Command.send!} for more details

# File lib/m2x/client.rb, line 81
def send_command(params)
  M2X::Client::Command.send!(self, params)
end
status() click to toggle source

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.

@return {Response} the API Status

# File lib/m2x/client.rb, line 37
def status
  get("/status")
end
time() click to toggle source

Method for {m2x.att.com/developer/documentation/v2/time Time} API

@return (Response) text/plain response of the server time in all three formats

# File lib/m2x/client.rb, line 211
def time
  get("/time").json
end
time_iso8601() click to toggle source

Method for {m2x.att.com/developer/documentation/v2/time Time} API

@return (Response) text/plain response of the server time in ISO 8601 Format

# File lib/m2x/client.rb, line 232
def time_iso8601
  get("/time/iso8601").raw
end
time_millis() click to toggle source

Method for {m2x.att.com/developer/documentation/v2/time Time} API

@return (Response) text/plain response of the server time in millis

# File lib/m2x/client.rb, line 225
def time_millis
  get("/time/millis").raw
end
time_seconds() click to toggle source

Method for {m2x.att.com/developer/documentation/v2/time Time} API

@return (Response) text/plain response of the server time in seconds

# File lib/m2x/client.rb, line 218
def time_seconds
  get("/time/seconds").raw
end

Private Instance Methods

default_headers() click to toggle source
# File lib/m2x/client.rb, line 291
def default_headers
  @headers ||= { "User-Agent" => USER_AGENT }.tap do |headers|
                 headers["X-M2X-KEY"] = @api_key if @api_key
               end
end
request(verb, path, qs=nil, params=nil, headers=nil) click to toggle source
# File lib/m2x/client.rb, line 244
def request(verb, path, qs=nil, params=nil, headers=nil)
  url = URI.parse(File.join(api_base, versioned(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

  @last_response = Response.new(res)
end
versioned(path) click to toggle source
# File lib/m2x/client.rb, line 283
def versioned(path)
  versioned?(path) ? path : "/#{api_version}#{path}"
end
versioned?(path) click to toggle source
# File lib/m2x/client.rb, line 287
def versioned?(path)
  path =~ /^\/v\d+\//
end