Skip to content

Latest commit

 

History

History
235 lines (181 loc) · 5.62 KB

README.markdown

File metadata and controls

235 lines (181 loc) · 5.62 KB
Raw

Slim-API Ruby

Accessing SlimApi and work with clients, contracts, campaigns and statistics

Instalation

Just in console

gem install slim-api-ruby

Or put into Gemfile

gem "slim-api-ruby"

and somewhere before use (not rails - they will require gem automaticaly)

require "slim-api"

Initialization

Setup your config values

SlimApi.api_token = "YOUR_TOKEN"
SlimApi.taxonomy = "YOUR_TAXONOMY"

#optional settings
SlimApi.version = :v1
#default is :v1

#url where is slim api located
SlimApi.url = "http://slimapi.ataxo.com"

# (default) When asked for not found object by id
# this will return nil:
SlimApi.not_found_handling = :nil
# this will raise exception SlimApiError::NotFound
SlimApi.not_found_handling = :exception

Logging

When you need to log requests use:

SlimApi.logger = Logger.new(STDOUT)
#or
SlimApi.logger = Logger.new("slimapi.log")

this will return you:

--------------------------------------------------------------------------------
Header: {"Api-Token"=>"YOUR TOKEN", "Content-Type"=>"application/json"}
Request: find
URL: http://slimapi.ataxo.com/v1/sandbox/objects
{
  "status": "ok",
  "code": 200,
  "message": "ok",
  "executed_at": "2013-03-12 11:31:21",
  "executed_in": "0.017648806s",
  "objects": [
    {
      ......
    }
  ],
  "total_count": 1
}

Working with Gem

You can access Main classes: Client, Contract, Campaign, Statistics, Category

How classes works

SlimApi documentation

# Find some objects:
campaigns = SlimApi::Client.find
# you got [ <Client:..>, ... ] and choose first one
campaign = campaigns.first
# then you can ask for something
campaign.name #=> "Client Name"
campaign.id #=> 123456

Arguments from api is hash, this hash is saved by hashr directly into instance. Instance is still Hash, you can do all stuf like with normal hash.

Find

# By id
SlimApi::Client.find 123
#=> <Client:..> #or on not found => nil or exception (by settings)

# By array of ids
SlimApi::Client.find 123, 234, 345
#=> [ <Client:..>, <Client:..>, <Client:..> ]

# By hash
SlimApi::Client.find
#=> [ <Client:..>, ... ]

SlimApi::Campaign.find
#=> [ <Campaign:..>, ... ]

#to find all clients with name
clients = SlimApi::Client.find :name => 'John'
#=> [ <Client:..>, ... ]

#and find campaigns under one client
clients.first.campaigns
#=> [ <Campaign:..>, ... ]

(Don't forget: all find queries generated by Query interface or by find({}) are limited by LIMIT!!!)

Query interface

ActiveRecord like query interface.

Supported methods:

  • where (conditions)
  • order
  • limit
  • offset
  • includes (include fields - statistics, payments)
query = SlimApi::Client.where(:name => "John")
#=> <SlimApi::SlimQuery: :where => {:name => 'John'} ... >

# you can chain all methods multiple times together to get your query like:
query = query.order('name desc').order('surname').limit(20).offset(12).where('age.gte' => 10)

# unless you call any enumerable method on query object, it will not load any data
# after first run, it will remember result in loaded_array and all enumerable methods will be delegated to it

query.each do |client|
  puts client.name
end

if you want to know what exactly is going under query interface, you can write

query.explain
#=> {:limit=>20, :offset=>12, :name=>"John", :"age.gte"=>10, :order=>"name desc,surname"}

this is exact hash which will be transformed into url params and added to GET request on right model

Hierarchy

look into documentation: SlimApi documentation

Statistics

In documentation you will find how to work with statistics api.

In gem you can use it same as in api:

SlimApi::Statistics.find :campaign_id => 1234, :'date.from' => Date.today - 10, :include => 'currency,partner_id,date', :order => 'date desc'

or by query interface

SlimApi::Statistics.where(:campaign_id => 1234).where(:'date.from' => Date.today - 10)
    .includes('currency').includes('partner_id').includes('date').order('date desc')

Order

You can order you find requests:

SlimApi::Client.find :order => 'name desc'
#or multiple orders:
SlimApi::Client.find :order => 'name desc,email asc'

or by query interface

SlimApi::Client.order('name desc').order('email asc')

Pagination

we added some functionality to array returned by method find

#default pagination setup
SlimApi.find_options
#=> { limit: 10, offset: 0 }
# and you can setup it by:
SlimApi.find_options = { limit: 20, offset: 0 }
#this is default configuration for all find methods,
#but you can easily overwrite for one call it by adding limit/offset to find method:
SlimApi::Client.find limit: 15

#get first page of clients (in db is 25 clients mathching find, but you will get only 10 default find limit)
clients = SlimApi::Client.find
#=> [ <Client: 1..>, <Client: 2..>, <Client: 3..> .., <Client: 10..>]
clients.total_count
#=> 25 #this will tell you how many items can be getted
clients.has_next_page?
#=> true #this will tell you if you can do .next_page
clients.limit
#=> 10 #show find limit
clients.offset
#=> 0 #show find current offset
clients.page_count
#=> 3 #show how many pages you can get
clients.actual_page
#=> 1 #show current page

# this will return you new array with new data, but with offset changed to offset + limit
second_page_of_clients = clients.next_page
#=> [ <Client: 11..>, <Client: 12..>, <Client: 13..> .., <Client: 20..>]

second_page_of_clients.offset
#=> 10
second_page_of_clients.actual_page
#=> 2

Copyright

Copyright (c) 2012 Ondrej Bartas. See LICENSE.txt for further details.