WialonApi

wialon_api is a ruby client for a Wialon web-based GPS tracking software platform API.

Installation

Add this line to your application's Gemfile:

gem 'wialon_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install wialon_api

Usage

Api method call

# The first thing to do is to authorize client
client = WialonApi.authorize("wialon_test", "test")

# Now we can use API
client.core.get_account_data(type: 1)
# => {"plan"=>"Gurtam External",
#  "enabled"=>1,
#  "flags"=>16,
#  "created"=>1362386585,
#  "balance"=>"0.00",
#  "daysCounter"=>0,
#  "services"=>
#   ....

# API calls with nested params could be implemented as follows
client.core.search_items({
  "spec" => {
    "itemsType" => "avl_unit",
    "propName" => "sys_name",
    "propValueMask" => "*",
    "sortType" => "sys_name"
  },
  "force" => 1,
  "flags" => 0x3FFFFFFFFFFFFFFF,
  "from" => 0,
  "to" => 0
})

=> {"searchSpec"=>{"itemsType"=>"avl_unit", "propName"=>"sys_name", "propValueMask"=>"*", "sortType"=>"sys_name", "propType"=>""},
# "dataFlags"=>4611686018427387903,
# "totalItemsCount"=>27,
# "indexFrom"=>0,
# "indexTo"=>0,
# "items"=>
#  [{"nm"=>"_TK102",
#    "cls"=>2,
#    "id"=>12417697,
#    "prp"=>{},
#    "crt"=>717313,
#     ..........

wialon_api uses a list of namespaces from API documentation:

core
items
user
resource
account
unit
unit_group
retranslator
route
messages
report
exchange
render
file

Error handling

When wialon server returns an error, the WialonApi::Error exception is raised

[1] pry(main)> WialonApi.authorize("wrong_user", "password")
WialonApi::Error: Wialon server https://hst-api.wialon.com/wialon/ajax.html returned error 8: Invalid user name or password

Logging

wialon_api logs information in STDOUT by default. This can be changed in configuration to any other logger e.g. Rails.logger.

Three types of information could be logged:

	configuration key	default value	log level
URL Request	`log_requests`	`true`	`debug`
error response JSON	`log_errors`	`true`	`warn`
success response JSON	`log_responses`	`false`	`debug`

In a rails applications with default settings in production mode only server response errors are logged. In development mode the gem logs server responses and request URLs.

Configuration

Global parameters could be set in a block of WialonApi.configure:

WialonApi.configure do |config|
  # Faraday adapter to make requests with:
  # config.adapter = :net_http

  # Faraday connection options
  # config.faraday_options = {}

  # HTTP verb for API methods (:get or :post)
  # config.http_verb = :post

  # Number of retries when connection is failed
  # config.max_retries = 1


  # Logging parameters:
  # log everything through the rails logger
  config.logger = Rails.logger

  # log requests' URLs
  # config.log_requests = true

  # log response JSON after errors
  # config.log_errors = true

  # log response JSON after successful responses
  # config.log_responses = false

  # Wialon server host
  # config.wialon_host = 'https://hst-api.wialon.com/wialon/ajax.html'

  # Wialon server edition: :hosting, :local, :pro
  # config.wialon_edition = :hosting
end

Note that Wialon Pro edition uses different parameters in requests, e.g. ssid vs eid as the session identifier. WialonApi gem handles these differences automatically.

Net::HTTP is used by default for a HTTP requests. One can choose any other adapter suported by faraday.

Options for faraday connection (e.g. proxy settings or SSL certificates path) could be set through faraday_options when configuring wialon_api.

The default configuration could be generated in a Rails application using wialon_api:install command:

$ cd /path/to/app
$ rails generate wialon_api:install

TODO

Implement methods from "Other request" documentation section
Add documentation

Contributing

Fork it ( https://github.com/[my-github-username]/wialon_api/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request