VK-RUBY

Build Status Code Climate Gem Version Dependency Status

Ruby wrapper for vk.com API. Documentation.

VK-RUBY gives you full access to all API features:

To get started, you need to register with vk.com own application and get the keys and read VK API documentation.

Installation

gem install vk-ruby

How to use

Create new application

VK-RUBY has many configuration parameters, they are passed in when creating the application. Complete list, see the configuration section.

app = VK::Application.new(app_id: 1, version: '5.20', access_token: '[TOKEN]')

API method calling

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

or

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

or

app.vk_call 'friends.getOnline', {uid: 1} # => Online friends

The parameters passed to the method call, have a higher priority than the configuration settings. In this example, API version upon request will be equal to 5.1.

VK::Application.new(version: '5.0').get_online(uid: 1, v: '5.1') # HTTP request with v=5.1 param

Parallel API method calling

VK-RUBY also supports parallel execution of requests. More information about parallel requests.

require 'typhoeus'
require 'typhoeus/adapters/faraday'

app.adapter = :typhoeus

manager = Typhoeus::Hydra.new(max_concurrency: 10) # (200 is default)
#manager.disable_memoization

uids = { 1 => {}, 2 => {}, 3 => {}}

app.in_parallel(manager) do 
  uids.each do |uid,_|
    app.users.get(user_ids: uid).each do |user|
      uids[user["id"]] = user
    end
  end
end

puts uids 
#=> {
#  1 => {"id"=>1, "first_name"=>"Павел", "last_name"=>"Дуров"}, 
#  2 => {"id"=>2, "first_name"=>"Александра", "last_name"=>"Владимирова", "hidden"=>1}, 
#  3 => {"id"=>3, "first_name"=>"DELETED", "last_name"=>"", "deactivated"=>"deleted"}
#}

Uploading files

Uploading files to vk servers performed in 3 steps:

  1. Getting url to download the file.
  2. File download.
  3. 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.

app.upload(
  'http://example.vk.com/path',{
    file1: ['/path/to/file1.jpg', 'image/jpeg'],
    file2: [File.open('/path/to/file2.png'), 'image/png', '/path/to/file2.png'] 
})

or

app.upload(
  'http://example.vk.com/path',[
    ['/path/to/file1.jpg', 'image/jpeg'],
    [File.open('/path/to/file2.png'), 'image/png', '/path/to/file2.png']
])

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.

Site

Site authorization process consists of 4 steps:

  1. Opening the browser to authenticate the user on the VK
  2. Permit the user to access their data
  3. Transfer site value code for the access key
  4. Preparation of the application server access key access_token to access the VK API

For the first step you need to generate correct URL

app.authorization_url({
  type: :site,
  app_id: 123,
  settings: 'friends,audio',
  version: '5.20',
  redirect_uri: 'https://example.com/'
})

#=> "https://oauth.vk.com/authorize?client_id=123&scope=friends,audio&redirect_uri=https://example.com/&response_type=token&v=5.20"

Once user permit the to access their data, on specified :redirect_url come GET request with code parameter, which is used to obtain an access_token.

app.site_auth(code: request_params[:code]) #=> { "access_token" : '[TOKEN]', "expires_in" : "100500"}

Server

To access the administrative methods API, which does not require user authentication, you need to get a special access_token. To obtain the key required when creating an application to specify the correct :app_id and :app_secret to the method server_auth.

app.server_auth(app_id: '[APP_ID]', app_secret: '[SECRET]') #=> { "access_token" : '[TOKEN]' }

Standalone (Client)

VK have a client authentication method, it implies a use of using a browser on the client (for example, UIWebView component when creating applications for iOS). In RUBY we can not afford it, and so we use the Mechanize. Most likely it is contrary to the rules of use API, so be careful ;-)

VK implies that the authorization process will consist of three steps:

  • Opening the browser to authenticate the user on the site VK
  • Permit the user to access their data
  • Transfer to the application key access_token to access the API

But VK-RUBY reduces this process in just a single method call

app.client_auth(login: '[LOGIN]', password: '[PASSWORD]') #=> { "access_token" : '[TOKEN]', "expires_in" : "100500"} }

Configuration

VK-RUBY has a large number of configuration attributes. You can pass them when you create the application, and the method call.

# global config
VK.configure do |config|
  config.app_id = 1
end

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

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

app = VK::Application.new do |a|
  a.app_id = 3
end

app.app_id #=> 3

In this example, the configuration is only one key, so it does not look difficult.

Below are all the configuration keys for VK-RUBY.

Name Description Default
:app_id Application ID nil
:app_secret Application secret nil
:version API version '5.20'
:redirect_uri Application redirect URL nil
:settings Application settings 'notify,friends,offline'
:access_token Access token nil
:verb HTTP verb :post
:host API host https://api.vk.com
:timeout Request timeout 10
:open_timeout Open connection timeout 3
:parallel_manager Parallel request manager nil
:proxy Proxy settings nil see proxy configuration section
:ssl SSL settings see ssl configuration section
:middlewares Faraday middlewares stack see middlewares section

SSL configuration

Name Default
:verify true
:verify_mode OpenSSL::SSL::VERIFY_NONE
:ca_file nil
:ca_path nil
:cert_store nil
:client_cert nil
:client_key nil
:certificate nil
:private_key nil
:verify_depth nil
:version nil

More information on configuring ssl documentation faraday

Proxy configuration

Name Default
:uri nil
:user nil
:password nil

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 stack

This stack consists of standard :multipart,:url_encoded, :json middlewares, details of which are looking at here.

Are also used:

  • :http_errors throws an exception if the HTTP status header is different from the 200
  • :api_errors throws an exception if the server response contains the API error

And here is set on the default HTTP adapter (Net::HTTP).

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

  faraday.response :api_errors
  faraday.response :json, content_type: /\bjson$/
  faraday.response :http_errors

  faraday.adapter Faraday.default_adapter
end

Expanding stack

app.middlewares = proc do |faraday|
  faraday.request :multipart
  faraday.request :url_encoded
  faraday.request :retry, max: 5,
                          interval: 0.3,
                          interval_randomness: 0.5,
                          backoff_factor: 2,
                          exceptions: [VK::ApiException,
                                       VK::BadResponseException,
                                       Faraday::TimeoutError]

  faraday.response :api_errors
  faraday.response :json, content_type: /\bjson$/
  faraday.response :http_errors
  faraday.response :vk_logger, logger: Logger.new('/path/to/file.log')

  faraday.adapter :net_http_persistent
end

In this example, additional used :retry middleware. It allows you to conveniently handle certain exceptions specified number of times with a certain interval – very convenient ;-) Also defined here is not the default HTTP adapter (Net::HTTP::Persistent).

Read more middleware usage.

IRB integration

Interactive ruby shell integration

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.

Copyright

Copyright (c) 2014 Andrew Zinenko. See LICENSE.txt for further details.