vkontakte_api 0.2.1 → 1.0.rc

data/.rspec

@@ -0,0 +1 @@
+--color --format=documentation

data/.travis.yml

@@ -2,3 +2,4 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - ruby-head

data/.yardopts

@@ -1,3 +1,3 @@
---files README.md,README.ru.md
+--files README.md
 --markup markdown
 --markup-provider redcarpet

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## 1.0 (в разработке)
+
+* rails-генератор конфиг-файла
+* Загрузка файлов на сервера ВКонтакте
+* Авторизация
+* Переход на JSON-парсер `Oj`
+* Результаты методов в виде `Hashie::Mash`
+* Настраиваемый логгер
+
+## 0.2.1 (31.03.2012)
+
+* Пространство имен `stats`
+
+## 0.2 (11.03.2012)
+
+* Подчищенные неавторизованные запросы
+* Документация кода (`YARD`)
+* Поддержка аргументов-массивов
+* Обновленный список пространств имен
+
+## 0.1 (31.01.2012)
+
+* Первая стабильная версия

data/README.md

@@ -1,115 +1,190 @@
-# vkontakte_api [![Build Status](https://secure.travis-ci.org/7even/vkontakte_api.png)](http://travis-ci.org/7even/vkontakte_api)
+## vkontakte_api [![Build Status](https://secure.travis-ci.org/7even/vkontakte_api.png)](http://travis-ci.org/7even/vkontakte_api) [![Dependency Status](https://gemnasium.com/7even/vkontakte_api.png)](https://gemnasium.com/7even/vkontakte_api) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/7even/vkontakte_api)
 
-`vkontakte_api` is a Ruby wrapper for VKontakte API. It allows you to call all API methods in the simplest possible way.
+`vkontakte_api` - ruby-адаптер для ВКонтакте API. Он позволяет вызывать методы API, загружать файлы на сервера ВКонтакте, а также поддерживает все 3 доступных способа авторизации (при этом позволяя использовать стороннее решение).
 
-Below is the English version of the readme. Russian version is located [here](https://github.com/7even/vkontakte_api/blob/master/README.ru.md).
+## Установка
 
-## Installation
+``` ruby
+# Gemfile
+gem 'vkontakte_api', '~> 1.0.rc'
+```
 
-``` bash
-gem install vkontakte_api
+или просто
+
+``` sh
+$ gem install vkontakte_api
 ```
 
-## Usage
+## Использование
 
-Default HTTP request library is `Net::HTTP`. You can set any other adapter supported by `faraday` in the configure block like so:
+### Вызов методов
 
 ``` ruby
-VkontakteApi.configure do |config|
-  config.adapter = :net_http
+# создаем клиент
+@vk = VkontakteApi::Client.new
+# и вызываем методы API
+@vk.users.get(uid: 1)
+
+# в ruby принято использовать snake_case в названиях методов,
+# поэтому likes.getList становится likes.get_list
+@vk.likes.get_list
+# также названия методов, которые возвращают '1' или '0',
+# заканчиваются на '?', а возвращаемые значения приводятся
+# к true или false
+@vk.is_app_user? # => false
+
+# если ВКонтакте ожидает получить параметр в виде списка,
+# разделенного запятыми, то его можно передать массивом
+users = @vk.users.get(uids: [1, 2, 3])
+
+# большинство методов возвращает структуры Hashie::Mash
+# и массивы из них
+users.first.uid        # => 1
+users.first.first_name # => "Павел"
+users.first.last_name  # => "Дуров"
+users.first.online?    # => true
+
+# если метод, возвращающий массив, вызывается с блоком,
+# то блок будет выполнен для каждого элемента,
+# и метод вернет обработанный массив
+fields = [:first_name, :last_name, :screen_name]
+@vk.friends.get(fields: fields) do |friend|
+  "#{friend.first_name} '#{friend.screen_name}' #{friend.last_name}"
 end
+# => ["Павел 'durov' Дуров"]
 ```
 
-All requests are sent via `VkontakteApi::Client` instance.
+### Загрузка файлов
+
+Загрузка файлов на сервера ВКонтакте осуществляется в несколько этапов: сначала вызывается метод API, возвращающий URL для загрузки, затем происходит сама загрузка файлов, и после этого в некоторых случаях нужно вызвать другой метод API, передав в параметрах данные, возвращенные сервером после предыдущего запроса. Вызываемые методы API зависят от типа загружаемых файлов и описаны в [соответствующем разделе документации](http://vk.com/developers.php?oid=-1&p=%D0%9F%D1%80%D0%BE%D1%86%D0%B5%D1%81%D1%81_%D0%B7%D0%B0%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B8_%D1%84%D0%B0%D0%B9%D0%BB%D0%BE%D0%B2_%D0%BD%D0%B0_%D1%81%D0%B5%D1%80%D0%B2%D0%B5%D1%80_%D0%92%D0%9A%D0%BE%D0%BD%D1%82%D0%B0%D0%BA%D1%82%D0%B5).
+
+Файлы передаются в формате хэша, где ключом является название параметра в запросе (указано в документации, например для загрузки фото на стену это будет `photo`), а значением - массив из 2 строк: полный путь к файлу и его MIME-тип:
 
 ``` ruby
-@app = VkontakteApi::Client.new
+url = 'http://cs303110.vkontakte.ru/upload.php?act=do_add'
+VkontakteApi.upload(url: url, photo: ['/path/to/file.jpg', 'image/jpeg'])
 ```
 
-To create a client able to perform authorized requests you need to pass an access token.
+Метод вернет ответ сервера ВКонтакте, преобразованный в `Hashie::Mash`; его можно использовать при вызове метода API на последнем этапе процесса загрузки.
+
+### Авторизация
+
+Для вызова большинства методов требуется токен доступа (access token). Чтобы получить его, можно использовать авторизацию, встроенную в `vkontakte_api`, либо положиться на какой-то другой механизм (например, [OmniAuth](https://github.com/intridea/omniauth)). В последнем случае в результате авторизации будет получен токен, который нужно будет передать в `VkontakteApi::Client.new`.
+
+Для работы с ВКонтакте API предусмотрено 3 типа авторизации: для сайтов, для клиентских приложений (мобильных либо десктопных, имеющих доступ к управлению браузером) и специальный тип авторизации серверов приложений для вызова административных методов без авторизации самого пользователя. Более подробно они описаны [тут](http://vk.com/developers.php?oid=-1&p=%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F); рассмотрим, как работать с ними средствами `vkontakte_api`.
+
+Для авторизации необходимо задать параметры `app_id` (ID приложения), `app_secret` (защищенный ключ) и `redirect_uri` (адрес, куда пользователь будет направлен после предоставления прав приложению) в настройках `VkontakteApi.configure`. Более подробно о конфигурировании `vkontakte_api` см. далее в соответствующем разделе.
+
+##### Сайт
+
+Авторизация сайтов проходит в 2 шага: сначала пользователь перенаправляется на страницу ВКонтакте для подтверждения запрошенных у него прав сайта на доступ к его данным. Со списком возможных прав можно ознакомиться [здесь](http://vk.com/developers.php?oid=-1&p=%D0%9F%D1%80%D0%B0%D0%B2%D0%B0_%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%B0_%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D0%B9). Допустим, нужно получить доступ к друзьям (`friends`) и фотографиям (`photos`) пользователя.
 
 ``` ruby
-@app = VkontakteApi::Client.new('my_access_token')
+redirect_to VkontakteApi.authorization_url(scope: [:friends, :photos])
 ```
 
-Probably the easiest way to get an access token in a web-app is using [OmniAuth](https://github.com/intridea/omniauth), but you can roll your own authentication if for some reason `OmniAuth` isn't acceptable. Currently `vkontakte_api` doesn't offer authentication functionality.
-
-Now you can call the API methods. All method names are underscore_cased as opposed to the [official documentation](http://vk.com/developers.php?oid=-17680044&p=API_Method_Description) where they are camelCased, so `getGroups` becomes `get_groups`. You can still call them in a camelCased manner, but that is not a Ruby-way practice.
+После подтверждения пользователь перенаправляется на указанный в настройках `redirect_uri`, причем в параметрах будет передан код, по которому можно получить токен доступа. `vkontakte_api` предоставляет метод `VkontakteApi.authorize`, который делает запрос к ВКонтакте, получает токен и создает клиент; нужно лишь передать ему код:
 
 ``` ruby
-@app.get_user_settings  # => 327710
-@app.groups.get         # => [1, 31022447]
+@vk = VkontakteApi.authorize(code: params[:code])
+# и теперь можно вызывать методы API на объекте @vk
+@vk.is_app_user?
 ```
 
-Predicate methods (those which begin with `is`, like `is_app_user`) are expected to return the result of some condition, so the '?' is appended to the end of the method name, and they return `true` or `false`:
+Также в этот момент полезно сохранить полученный токен в БД либо в сессии, чтобы использовать его повторно:
 
 ``` ruby
-@app.is_app_user? # => true
+current_user.token = @vk.token
+current_user.save
+# позже
+@vk = VkontakteApi::Client.new(current_user.token)
 ```
 
-You can still call these without a '?' and get `'1'` or `'0'` in result if you want to handle that yourself.
+##### Клиентское приложение
 
-Now for parameters. All method parameters are named, and you can pass them in a hash where parameter names are keys and parameter values are values:
+Авторизация клиентского приложения несколько проще - не нужно получать токен отдельным запросом, он выдается сразу после редиректа пользователя.
 
 ``` ruby
-@app.friends.get(fields: 'uid,first_name,last_name')
-# =>  [
-#       {
-#         :uid          => "1",
-#         :first_name   => "Павел",
-#         :last_name    => "Дуров"
-#       },
-#       {
-#         :uid          => "6492",
-#         :first_name   => "Andrew",
-#         :last_name    => "Rogozov"
-#       }
-#     ]
+# пользователь направляется на следующий урл
+VkontakteApi.authorization_url(type: :client, scope: [:friends, :photos])
 ```
 
-If the parameter value is a comma-separated list, you can pass it as an array - it will be properly handled before the request:
+Необходимо принимать во внимание, что `redirect_uri` нужно выставлять на `http://api.vkontakte.ru/blank.html`, иначе не получится вызывать методы, доступные клиентским приложениям.
+
+Когда пользователь подтвердит права приложения, он будет перенаправлен на `redirect_uri`, при этом в параметре `access_token` будет токен, который нужно передать в `VkontakteApi::Client.new`.
+
+##### Сервер приложения
+
+Последний тип авторизации - самый простой, т.к. не предполагает участия пользователя.
 
 ``` ruby
-users_ids = [1, 6492]
-@app.users.get(uids: users_ids) # => same output as above
+@vk = VkontakteApi.authorize(type: :app_server)
 ```
 
-It's also worth noting that all returned hashes have symbolized keys.
+### Обработка ошибок
 
-If the response is an Enumerable, you can pass a block that will yield each successive element and put the result in the returned array (like `Enumerable#map` does):
+Если ВКонтакте API возвращает ошибку, выбрасывается исключение класса `VkontakteApi::Error`.
 
 ``` ruby
-@app.friends.get(fields: 'first_name,last_name') do |friend|
-  "#{friend[:first_name]} #{friend[:last_name]}"
-end
-# => ["Павел Дуров", "Andrew Rogozov"]
+vk = VK::Client.new
+vk.friends.get(uid: 1, fields: [:first_name, :last_name, :photo])
+# VkontakteApi::Error: VKontakte returned an error 7: 'Permission to perform this action is denied' after calling method 'friends.get' with parameters {"uid"=>"1", "fields"=>"first_name,last_name,photo"}.
 ```
 
-`vkontakte_api` doesn't keep any method names list inside (except method namespaces like `friends` or `groups`) - when you call a method, it's name is camelcased before sending a request to VKontakte. So when a new method is added to the API, you don't need to wait for the new version of `vkontakte_api` gem - you can use that new method immediately. If you mistype the method name or use a method you don't have rights to call, you will get an exception with a relevant message (more about the exceptions below).
+### Логгирование
+
+`vkontakte_api` логгирует служебную информацию о запросах при вызове методов. По умолчанию все пишется в `STDOUT`, но в настройке можно указать любой другой совместимый логгер, например `Rails.logger`.
+
+Есть возможность логгирования 3 типов информации, каждому соответствует ключ в глобальных настройках.
+
+|                        | ключ настройки  | по умолчанию | уровень логгирования |
+| ---------------------- | --------------- | ------------ | -------------------- |
+| URL запроса            | `log_requests`  | `true`       | `debug`              |
+| JSON ответа при ошибке | `log_errors`    | `true`       | `warn`               |
+| JSON удачного ответа   | `log_responses` | `false`      | `debug`              |
 
-### Error handling
+Таким образом, в rails-приложении с настройками по умолчанию в production записываются только ответы сервера при ошибках; в development также логгируются URL-ы запросов.
 
-If VKontakte returns an error in response, you get a `VkontakteApi::Error` exception with all meaningful information that can be retrieved:
+## Настройка
+
+Глобальные параметры `vkontakte_api` задаются в блоке `VkontakteApi.configure` следующим образом:
 
 ``` ruby
-@app.audio.get_by_id
-# => VkontakteApi::Error: VKontakte returned an error 1: 'Unknown error occured' after calling method 'audio.getById' with parameters {}.
+VkontakteApi.configure do |config|
+  # параметры, необходимые для авторизации средствами vkontakte_api
+  # (не нужны при использовании сторонней авторизации)
+  config.app_id       = '123'
+  config.app_secret   = 'AbCdE654'
+  config.redirect_uri = 'http://example.com/oauth/callback'
+  
+  # faraday-адаптер для сетевых запросов
+  config.adapter = :net_http
+  
+  # логгер
+  config.logger        = Rails.logger
+  config.log_requests  = true  # URL-ы запросов
+  config.log_errors    = true  # ошибки
+  config.log_responses = false # удачные ответы
+end
 ```
 
-## Changelog
+По умолчанию для HTTP-запросов используется `Net::HTTP`; можно выбрать [любой другой адаптер](https://github.com/technoweenie/faraday/blob/master/lib/faraday/adapter.rb), поддерживаемый `faraday`.
+
+Чтобы сгенерировать файл с настройками по умолчанию в rails-приложении, можно воспользоваться генератором `vkontakte_api:install`:
+
+``` sh
+$ cd /path/to/app
+$ rails generate vkontakte_api:install
+```
 
-* 0.1 Initial stable version
-* 0.2 Array arguments support, cleaned up non-authorized requests, updated namespaces list, code documentation
-* 0.2.1 `stats` namespace
+## JSON-парсер
 
-## Roadmap
+`vkontakte_api` использует парсер [Oj](https://github.com/ohler55/oj) - это единственный парсер, который не показал [ошибок](https://github.com/7even/vkontakte_api/issues/1) при парсинге JSON, генерируемого ВКонтакте.
 
-* Logging requests
-* Authentication (getting the access_token from VK)
-* Maybe Struct-like objects in result (instead of Hashes)
+Также в библиотеке `multi_json` (обертка для различных JSON-парсеров, которая выбирает самый быстрый из установленных в системе и парсит им) `Oj` поддерживается и имеет наивысший приоритет; поэтому если он установлен в системе, `multi_json` будет использовать именно его.
 
-## Contributing
+## Участие в разработке
 
-If you want to contribute to the project, fork the repository, push your changes to a topic branch and send me a pull request.
+Если вы хотите поучаствовать в разработке проекта, форкните репозиторий, положите свои изменения в отдельную ветку и отправьте мне pull request.
 
-`vkontakte_api` is tested under MRI `1.8.7`, `1.9.2` and `1.9.3`. If something is working incorrectly or not working at all in one of these environments, this should be considered a bug. Any bug reports are welcome at Github issues.
+`vkontakte_api` тестируется под MRI `1.8.7`, `1.9.2`, `1.9.3` и `2.0.0-dev`. Если в одной из этих сред что-то работает неправильно, либо вообще не работает, то это следует считать багом, и написать об этом в [issues на Github](https://github.com/7even/vkontakte_api/issues).

data/lib/generators/vkontakte_api/install/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Create a vkontakte_api config file in config/initializers/vkontakte_api.rb.

data/lib/generators/vkontakte_api/install/install_generator.rb

@@ -0,0 +1,9 @@
+# A rails generator `vkontakte:install`. It creates a config file in `config/initializers/vkontakte_api.rb`.
+class VkontakteApi::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path('../templates', __FILE__)
+  
+  # Creates the config file.
+  def create_initializer
+    copy_file 'initializer.rb', 'config/initializers/vkontakte_api.rb'
+  end
+end

data/lib/generators/vkontakte_api/install/templates/initializer.rb

@@ -0,0 +1,22 @@
+VkontakteApi.configure do |config|
+  # Authorization parameters (not needed when using an external authorization):
+  # config.app_id       = '123'
+  # config.app_secret   = 'AbCdE654'
+  # config.redirect_uri = 'http://example.com/oauth/callback'
+  
+  # Faraday adapter to make requests with:
+  # config.adapter = :net_http
+  
+  # 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
+end

data/lib/vkontakte_api/api.rb

@@ -1,50 +1,38 @@
 module VkontakteApi
-  # A low-level module which handles the requests to VKontakte and returns their results as hashes with symbolized keys.
+  # A low-level module which handles the requests to VKontakte API and returns their results as mashes.
   # 
-  # It uses Faraday underneath the hood.
+  # It uses Faraday with middleware underneath the hood.
   module API
-    BASE_HOST = 'https://api.vkontakte.ru'
-    BASE_URL  = '/method/'
+    # URL prefix for calling API methods.
+    URL_PREFIX = 'https://api.vkontakte.ru/method'
     
     class << self
-      # Main interface method.
+      # API method call.
       # @param [String] method_name A full name of the method.
-      # @param [Hash] args Method arguments including the access token.
-      # @return [Hash] The result of the method call.
-      # @raise [VkontakteApi::Error] raised when VKontakte returns an error.
-      def call(method_name, args = {}, &block)
-        connection = Faraday.new(:url => BASE_HOST) do |builder|
-          builder.adapter(VkontakteApi.adapter)
-        end
-        
-        url = url_for(method_name, args)
-        body = connection.get(url).body
-        response = Yajl::Parser.parse(body, :symbolize_keys => true)
-        
-        if response.has_key?(:error)
-          raise VkontakteApi::Error.new(response[:error])
-        else
-          response[:response]
-        end
+      # @param [Hash] args Method arguments.
+      # @param [String] token The access token.
+      # @return [Hashie::Mash] Mashed server response.
+      def call(method_name, args = {}, token = nil)
+        flat_arguments = Utils.flatten_arguments(args)
+        connection(:url => URL_PREFIX, :token => token).get(method_name, flat_arguments).body
       end
       
-    private
-      def url_for(method_name, arguments)
-        flat_arguments = flatten_arguments(arguments)
-        "#{BASE_URL}#{method_name}?#{flat_arguments.to_param}"
-      end
-      
-      def flatten_arguments(arguments)
-        arguments.inject({}) do |flat_args, (arg_name, arg_value)|
-          flat_args[arg_name] = if arg_value.respond_to?(:join)
-            # if value is an array, we join it with a comma
-            arg_value.join(',')
-          else
-            # otherwise leave it untouched
-            arg_value
-          end
-          
-          flat_args
+      # Faraday connection.
+      # @param [Hash] options Connection options.
+      # @option options [String] :url Connection URL (either full or just prefix).
+      # @option options [String] :token OAuth2 access token (not used if omitted).
+      # @return [Faraday::Connection] Created connection.
+      def connection(options = {})
+        url   = options.delete(:url)
+        token = options.delete(:token)
+        
+        Faraday.new(url) do |builder|
+          builder.request  :oauth2, token unless token.nil?
+          builder.request  :multipart
+          builder.response :vk_logger
+          builder.response :mashify
+          builder.response :oj, :preserve_raw => true
+          builder.adapter  VkontakteApi.adapter
         end
       end
     end

data/lib/vkontakte_api/authorization.rb

@@ -0,0 +1,66 @@
+module VkontakteApi
+  # A module containing the methods for authorization.
+  # 
+  # @note `VkontakteApi::Authorization` extends `VkontakteApi` so these methods should be called from the latter.
+  module Authorization
+    # Authorization options.
+    OPTIONS = {
+      :client => {
+        :site          => 'https://oauth.vk.com',
+        :authorize_url => '/authorize',
+        :token_url     => '/access_token'
+      },
+      :client_credentials => {
+        'auth_scheme' => 'request_body'
+      }
+    }
+    
+    # URL for redirecting the user to VK where he gives the application all the requested access rights.
+    # @option options [Symbol] :type The type of authorization being used (`:site` and `:client` supported).
+    # @option options [String] :redirect_uri URL for redirecting the user back to the application (overrides the global configuration value).
+    # @option options [Array] :scope An array of requested access rights (each represented by a symbol or a string).
+    # @raise [ArgumentError] raises after receiving an unknown authorization type.
+    # @return [String] URL to redirect the user to.
+    def authorization_url(options = {})
+      type = options.delete(:type) || :site
+      # redirect_uri passed in options overrides the global setting
+      options[:redirect_uri] ||= VkontakteApi.redirect_uri
+      options[:scope] = VkontakteApi::Utils.flatten_argument(options[:scope]) if options[:scope]
+      
+      case type
+      when :site
+        client.auth_code.authorize_url(options)
+      when :client
+        client.implicit.authorize_url(options)
+      else
+        raise ArgumentError, "Unknown authorization type #{type.inspect}"
+      end
+    end
+    
+    # Authorization (getting the access token and building a `VkontakteApi::Client` with it).
+    # @option options [Symbol] :type The type of authorization being used (`:site` and `:app_server` supported).
+    # @option options [String] :code The code to exchange for an access token (for `:site` authorization type). 
+    # @raise [ArgumentError] raises after receiving an unknown authorization type.
+    # @return [VkontakteApi::Client] An API client.
+    def authorize(options = {})
+      type = options.delete(:type) || :site
+      
+      case type
+      when :site
+        code  = options.delete(:code)
+        token = client.auth_code.get_token(code)
+      when :app_server
+        token = client.client_credentials.get_token({}, OPTIONS[:client_credentials])
+      else
+        raise ArgumentError, "Unknown authorization type #{type.inspect}"
+      end
+      
+      Client.new(token)
+    end
+    
+  private
+    def client
+      @client ||= OAuth2::Client.new(VkontakteApi.app_id, VkontakteApi.app_secret, OPTIONS[:client])
+    end
+  end
+end

data/lib/vkontakte_api/client.rb

@@ -1,24 +1,26 @@
 module VkontakteApi
-  # A class representing a connection to VK. It holds an access token.
+  # A class representing a connection to VK. It holds the access token.
   class Client
+    include Resolver
+    
     # An access token needed by authorized requests.
-    attr_reader :access_token
+    attr_reader :token
     
     # A new API client.
-    # @param [String] access_token An access token.
-    def initialize(access_token = nil)
-      @access_token = access_token
+    # @param [String, OAuth2::AccessToken] token An access token.
+    def initialize(token = nil)
+      if token.respond_to?(:token)
+        # token is an OAuth2::AccessToken
+        @token = token.token
+      else
+        # token is a String or nil
+        @token = token
+      end
     end
     
     # Is a `VkontakteApi::Client` instance authorized.
     def authorized?
-      !@access_token.nil?
-    end
-    
-    # All unknown methods are delegated to a `VkontakteApi::Resolver` instance.
-    def method_missing(method_name, *args, &block)
-      args = args.first || {}
-      VkontakteApi::Resolver.new(:access_token => @access_token).send(method_name, args, &block)
+      !@token.nil?
     end
   end
 end

data/lib/vkontakte_api/configuration.rb

@@ -1,20 +1,34 @@
+require 'logger'
+
 module VkontakteApi
   # General configuration module.
   # 
-  # It extends `VkontakteApi` so it's methods should be called from there.
+  # @note `VkontakteApi::Configuration` extends `VkontakteApi` so these methods should be called from the latter.
   module Configuration
     # Available options.
-    OPTION_NAMES = [:app_id, :app_secret, :adapter]
+    OPTION_NAMES = [:app_id, :app_secret, :redirect_uri, :adapter, :logger, :log_requests, :log_errors, :log_responses]
     
     attr_accessor *OPTION_NAMES
     
+    alias_method :log_requests?,  :log_requests
+    alias_method :log_errors?,    :log_errors
+    alias_method :log_responses?, :log_responses
+    
     # Default HTTP adapter.
-    DEFAULT_ADAPTER = :net_http
+    DEFAULT_ADAPTER = Faraday.default_adapter
+    
+    # Logger default options.
+    DEFAULT_LOGGER_OPTIONS = {
+      :requests  => true,
+      :errors    => true,
+      :responses => false
+    }
     
     # A global configuration set via the block.
     # @example
     #   VkontakteApi.configure do |config|
     #     config.adapter = :net_http
+    #     config.logger  = Rails.logger
     #   end
     def configure
       yield self if block_given?
@@ -23,7 +37,11 @@ module VkontakteApi
     
     # Reset all configuration options to defaults.
     def reset
-      @adapter = DEFAULT_ADAPTER
+      @adapter       = DEFAULT_ADAPTER
+      @logger        = ::Logger.new(STDOUT)
+      @log_requests  = DEFAULT_LOGGER_OPTIONS[:requests]
+      @log_errors    = DEFAULT_LOGGER_OPTIONS[:errors]
+      @log_responses = DEFAULT_LOGGER_OPTIONS[:responses]
     end
     
     # When this module is extended, set all configuration options to their default values.

data/lib/vkontakte_api/error.rb

@@ -1,18 +1,17 @@
 module VkontakteApi
-  # An exception raised by `VkontakteApi::API` when VKontakte returns an error.
+  # An exception raised by `VkontakteApi::Result` when given a response with an error.
   class Error < StandardError
     # An error code.
     # @return [Fixnum]
     attr_reader :error_code
     
-    # An exception is initialized by the data from response hash.
+    # An exception is initialized by the data from response mash.
     # @param [Hash] data Error data.
     def initialize(data)
-      @error_code = data.delete(:error_code)
-      @error_msg  = data.delete(:error_msg)
-      @params     = {}
+      @error_code = data.error_code
+      @error_msg  = data.error_msg
       
-      request_params = parse_params(data.delete :request_params)
+      request_params = parse_params(data.request_params)
       
       @method_name  = request_params.delete('method')
       @access_token = request_params.delete('access_token')
@@ -23,7 +22,16 @@ module VkontakteApi
     # A full description of the error.
     # @return [String]
     def message
-      "VKontakte returned an error #{@error_code}: '#{@error_msg}' after calling method '#{@method_name}' with parameters #{@params.inspect}."
+      message = "VKontakte returned an error #{@error_code}: '#{@error_msg}'"
+      message << " after calling method '#{@method_name}'"
+      
+      if @params.empty?
+        message << " without parameters."
+      else
+        message << " with parameters #{@params.inspect}."
+      end
+      
+      message
     end
     
   private