croko/vk-ruby

#VK-RUBY

Ruby wrapper for vk.com API.

VK-RUBY gives you full access to all API features. Has several types of method naming and methods calling, optional authorization, file uploading, logging, irb integration, parallel method calling and any faraday-supported http adapter of your choice.

Compatible with Ruby 1.9.2, 1.9.3, Jruby and RBX.

To get started working with vk.com API. First of all, to register your own application and obtain the keys. Read vk api documentation.

vk-ruby documentation

Installation

gem install vk-ruby

How to use

API method calling

app = VK::Application.new access_token: TOKEN

app.friends.getOnline uid: 1 # => Online friends

# similar call

app.friends.get_online uid: 1

app.vk_call 'friends.getOnline', {uid: 1}

Parallel method call

app = VK::Application.new access_token: TOKEN

app.adapter = :em_http # :em_synchrony or :patron or :typhoeus

results = []

app.in_parallel do
  10.times do |i|
    results << app.friends.get_online uid: i
  end
end

result.size # => 10

Upload files

Uploading files to vk servers performed in 3 steps:

Getting url to download the file.
File download.
Save the file.

The first and third steps are produced by calls to certain API methods as described above. Details downloading files, see the relevant section of the documentation.

When you call the upload also need to specify the mime type file.

url = 'http://cs2222.vkontakte.ru/upload.php?act=do_add'

app.upload(url: url, photo: ['/path/to/example.jpg', 'image/jpeg'])

Authorization

VK has several types of applications and several types of authorization. They are different ways of authorization and access rights. more details refer to the documentation

Application

app = VK::Application.new app_id: 222, app_secret: 'secret key', redirect_uri: 'http://...'

app.authorize(type: :serverside, code: CODE) # => {"access_token":"533bacf01e11f55b536a565b57531ac114461ae8736d6506a3", "expires_in":43200, "user_id":6492}

# if app is secure application server

app.authorize(type: :secure) # => {"access_token":"533bacf01e11f55b536a565b57531ac114461ae8736d6506a3"}

Serverside(deprecated)

app = VK::Serverside.new app_id: 222, app_secret: 'secret key'

app.authorize(CODE) # => {"access_token":"533bacf01e11f55b536a565b57531ac114461ae8736d6506a3", "expires_in":43200, "user_id":6492}

Class VK::Serverside is deprecate. Please use VK::Application

Secure server(deprecated)

app = VK::Secure.new app_id: 222, app_secret: 'secret key'

app.authorize # => {"access_token":"533bacf01e11f55b536a565b57531ac114461ae8736d6506a3"}

Class VK::Secure is deprecate. Please use VK::Application

Standalone

Not supported

Class VK::Standalone is deprecate. Please use VK::Application

Configuration

Used to configure the gem attr_configurable The idea is the hierarchy of default parameters.

instance variable -> class constant -> module constant

module VK
  APP_ID = 111

  class Application
    APP_ID = 222
  end

  class Secure
  end
end

VK::Application.new.app_id # => 222

VK::Application.new(app_id: 333).app_id # => 333

VK::Secure.new.app_id # => 111

For configuration available this options:

logger application logger.
verb http verb request. Only :get or :post.
access_token your access token.
open_timeout open_timeout request.
timeout timeout request.
proxy proxy params request.
ssl indicating that you need to use ssl.

More information on configuring ssl documentation faraday

Middlewares

VK-RUBY based on faraday.

It is an HTTP client lib that provides a common interface over many adapters (such as Net::HTTP) and embraces the concept of Rack middleware when processing the request/response cycle.

Advanced middleware usage.

Default middlewares stack implementation

def faraday_middleware
  @faraday_middleware || proc do |faraday|
    # request params encoders
    faraday.request  :multipart
    faraday.request  :url_encoded

    # response body parse
    faraday.response :json, content_type: /\bjson$/

    # http adapter
    faraday.adapter  self.adapter
  end
end

Expanding stack

app.faraday_middleware = proc do |faraday|
  faraday.request  :multipart
  faraday.request  :url_encoded

  faraday.response :json, content_type: /\bjson$/
  faraday.response :normalize_utf     # UTF nfkd normalization
  faraday.response :validate_utf      # Remove invalid utf
  faraday.response :vk_logger, self.logger

  faraday.adapter  app.adapter
end

IRB mode

$ vk --help
  -h, --help                       Display this help and exit
  -v, --version                    Output version infomation and exit
  -e, --eval [code]                Evaluate the given code and exit
  -a, --access_token [token]       Your access token
  -t, --type [type]                Application type
  -i, --id [id]                    Application ID
  -s, --secret [secret]            Application secret
  -l, --logfile                    Logfile
  -T, --types                      List application types

$ vk -e 'puts vk.isAppUser'
0

$ vk -a 'your token'
001 > vk.access_token
002 > => "your token"

Contributing to vk-ruby

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

croko / vk-ruby