LeftClick Web Services

LWS is a library for Ruby provides access to the LeftClick web services/applications using a model-based structure that abstracts from API calls using the available REST interfaces.

Installation

In your Gemfile, add:

gem "lws"

or install the ruby-lws package.

Usage

First, you have to initialize the library. For example, with Rails, you would create a new config/initializers/lws.rb file with these lines:

# config/initializers/lws.rb
LWS.setup do |config|
  config.api_token = "…" # Get it from some place
end

After that, due to the fact that LWS is based on Spyke, you can access the objects in the LeftClick Web Services similary to many ActiveRecord-like ORM's:

Get all map markers of the first map

map = Maps::Map.all.first
markers = map.markers

Create an account for company with ID 6

company = Company.find(6)
account = Auth::Account.create(name: "Foo Bar",
                               company: company)

Destroy all locations named "Test"

loc = Presence::Location.where(name: "Test")
loc.destroy

Configuration

The following example uses a much more elaborate setup:

LWS.setup do |config|
  config.api_token_middleware = TokenAuthenticator
  config.caching_object = MyRedisCache.new
  config.environment = :development
  config.endpoints = { maps: "https://maps.leftclick.cloud" }
  config.http_caching = true
  config.http_debug = true
  config.json_debug = true
  config.logger = Rails.logger
  config.proxy = "http://proxyserver:8080"
end

In this setup, a caching object is used that follows the FaradayMiddleWare::Caching API. It uses all development API endpoints, except for maps, which is overriden to use the production endpoint. Also HTTP request and JSON data debug logging is enabled and LWS will use the Rails logger to log the messages. Also HTTP responses will be cached in accordance to their ETag/last modification time and the proxy server with URL http://proxyserver:8080 will be used. Finally, a custom API token authenticator class is used that should implement the Faraday::Middleware interface and set the X-Token header with the runtime determined API token as value, for example:

class TokenAuthenticator < Faraday::Middleware

  def call(env)
    env[:request_headers]["X-Token"] = … # Some calculated token
    @app.call(env)
  end

end

The LC_LWS_ENV environment variable is supported to override the LWS environment. Allowed values are "production" (default) and "development". The LC_LWS_API_TOKEN is supported to set the LWS API token default. This only works if a custom API token middleware is not used.

LWS Console

This library comes with the program lwsconsole, which is a command-line tool that can be used to interactively use the library. (This is similar to the Rails console.) See lwsconsole --help for the supported command-line arguments.

LWS Console will perform the setup for you and give you a prompt in the LWS module namespace or the module of an app if this is selected via the arguments. It uses the production environment per default using the token provided by a command-line argument. These defaults can be overriden using the configuration. For example, to rename a map:

$ lwsconsole -t "my_token" -a maps
[1] lwsconsole(LWS::Maps)> Map.all.map(&:name)
=> ["Gebouw 1",
    "Gebouw 3"]
[2] lwsconsole(LWS::Maps)> map = Map.find(2)
=> #<LWS::Maps::Map(maps/(:id)) id: 2 name: "Gebouw 3" ... markers: []>
[3] lwsconsole(LWS::Maps)> map.name = "Gebouw 2"
"Gebouw 2"
[4] lwsconsole(LWS::Maps)> map.save
nil

Besides the API calls, LWS console supports a few commands to change its behaviour:

• http_debug true|false: Toggles HTTP debugging for API calls
• http_debug_headers true|false: Toggles logging of HTTP headers in the HTTP debug output
• json_debug true|false: Toggles JSON debug output for API calls
• reload!: Reloads all apps

[5] lwsconsole(LWS::Maps)> http_debug true
true

LWS Console keeps a history of all calls and commands, use the command history --all to seem them. Use the command help to see all other available commands (provided by Pry).

Configuration files

LWS Console will look for the configuration files first in /etc/LeftClick/lws.yml and then ~/.config/LeftClick/lws.yml; they are in the YAML format.

The configuration file can set defaults per environment. It is possible to set the API key, endpoints and debug modes.

development:
  api_token: "my_token"
  endpoints:
    maps: "https://maps.leftclick.cloud
  http_debug: true
  http_debug_headers: true
  json_debug: true

To override the default environment or to set default options, use the default section. For example:

default:
  environment: "development"
  json_debug: true