VK-RUBY

(The project is closed and not supported.)

Ruby wrapper for vk.com API. Documentation.

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

• Has several types of methods naming and methods calling
• Parallel method calling
• All authorization methods
  • Site
  • Server
  • Standalone
• File uploading
• Any faraday features
• IRB integration

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.26', 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 upload the file.
2. File upload.
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.26',
  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.26"

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)

app.authorization_url({
  type: :client,
  app_id: 123,
  settings: 'friends,audio',
  version: '5.26',
  redirect_uri: 'https://example.com/',
  display: :mobile
})

# => "https://oauth.vk.com/authorize?client_id=123&scope=friends%2Caudio&redirect_uri=https%3A%2F%2Foauth.vk.com%2Fblank.html&display=mobile&response_type=token&v=5.26"

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.

SSL configuration

More information on configuring ssl documentation faraday

Proxy configuration

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::APIError,
                                       VK::BadResponse,
                                       Faraday::TimeoutError,
                                       Faraday::ConnectionFailed],
                          retry_if: lambda { |env, exception| true }

  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

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
• Install dependencies
• Install overcommit overcommit --install
• 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) 2016 Andrew Zinenko. See LICENSE.txt for further details.