Mailru-api

Mailru-api - это гем, предоставляющий простой и лаконичный способ взаимодействия с сервисами @MAIL.RU, реализованный на базе @MAIL.RU REST API (документацию можно найти по ссылке: http://api.mail.ru/docs/guides/restapi/).

Для того, чтобы установить гем выполните команду:

gem install mailru-api

или добавьте следующую строчку в свой Gemfile:

gem "mailru-api", :require => 'mailru/api'

Документация

Конфигурация
Вызов методов @MAIL.RU
Обработка результатов вызова
Примеры из реальной жизни

Конфигурация API

Перед тем как начать непосредственно вызывать методы @MAIL.RU, нужно создать и сконфигурировать API. Существуют несколько методов конфигурации:

Через DSL синтаксис:

 api = MailRU::API.new do
   app_id 'your app id is here'
   secret_key 'your secret key is here'
   session_key 'your session key is here when required'
   format MailRU::API::Format::XML
 end

Через конфигурирование в блоке

 api = MailRU::API.new do |configuration|
   configuration.app_id = 'your app id is here'
   configuration.secret_key = 'your secret key is here'
   configuration.session_key = 'your session key is here when required'
 end

Через параметры конструктора

 api = MailRU::API.new(
   app_id: 'your app id is here', 
   uid: 'the UID the request made on behalf of', 
   private_key: 'your private key is here',
   session_key: 'your session key is here when required'
 )

Путем комбинирования несколько методов конфигурации:

 api = MailRU::API.new(app_id: 'your app id is here', secret_key: 'your secret key is here') do
   secret_key 'your secret key is here'
   session_key 'your session key is here when required'
   private_key 'your private key is here'
 end

Путем обычной установки параметров

 api = MailRU::API.new
 app.app_id = 'your app id is here'
 app.secret_key = 'your secret key is here'
 ...

Поддерживаемые параметры конфигурации:

app_id	Идентификатор приложения
secret_key	Значение secret_key из настроек приложения
private_key	Значение private_key из настроек приложения
uid	Идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key
session_key	Сессия текущего пользователя
format	Формат ответа API; возможные значения: MailRU::API::Format::XML или MailRU::API::Format::JSON (по-умолчанию)

Более подробную информацию можно найти по ссылке http://api.mail.ru/docs/guides/restapi/

Вызов методов @MAIL.RU

После того как объект API создан и сконфигурирован можно начинать взаимодействовать с методами @MAIL.RU. Все методы @MAIL.RU REST API представленны соответствующими Ruby методами в underscore варианте. Например:

REST API метод: friends.getAppUsers
Ruby API метод: friends.get_app_users

Методы вызываются по схеме "Сервер-Сервер" везде, где это возможно. Если этого сделать не возможно (например, не был указан secret_key), будет сделана попытка вызвать метода по схеме "Клиент-Сервер".

Примеры вызова методов:

Метод audio.get:

  api.audio.get
  api.audio.get(limit: 10)
  api.audio.get(offset: 10, limit:20)

Метод notifications.send

  uids = ['uid1', 'uid2', ..., 'uidn'].join(',')
  text = 'hello'.encode('utf-8')
  api.notifications.send(uids: uids, text: text)

Метод users.hasAppPermission

  api.users.has_app_permission(ext_perm: 'events')

Что делать если @MAIL.RU обновил API, но их поддержка еще не добавленна в Mailru-api?

Любой метод можно вызвать выполнением HTTP GET или HTTP POST запроса. Для этого Mailru-api предоставляет два метода:

api.get(name, params = {}, secure = MailRU::API::Request::Secure::Any)
api.post(name, params = {}, secure = MailRU::API::Request::Secure::Any)

Вызов метода audio.get через HTTP GET

  api.get('audio.get')
  api.get('audio.get', limit:10)
  api.get('audio.get', offset: 2, limit: 10)

Вызов метода audio.get через HTTP POST
```
  api.post('audio.get')
```

Вызов метода notifications.send через HTTP POST

  uids = ['uid1', 'uid2', 'uid3'].join(',')
  text = 'Тексе сообщения.'.encoding('utf-8')

  api.post('notifications.send', {uids: uids, text: text})

Обработка результатов вызова

В зависимости от того, какой формат взаимодействия с API выбран, XML или JSON, все методы будут возвращать соответствующие объекты.

Примеры из реальной жизни

Пример 1

  require 'mailru/api'

  ...

  api = MailRU::API.new do |configuration|
    configuration.app_id = 'hidden'
    configuration.secret_key = 'hidden'
    configuration.session_key = 'hidden'
  end

  begin
    api.events.get_new_count
  rescue MailRU::API::PermissionDeniedError => e
    begin
      p "Can not obtain count of new events!"
      p "Has 'events' permission: #{api.users.has_app_permission(ext_perm: 'events')['events']}"
    rescue MailRU::API::Error => e
    end
  end

Пример 2

  uids = ['uid1', 'uid2', 'uid3'].join(',')
  text = message.encoding('utf-8')

  MailRU::API.new(app_id: 'hidden', secret_key: 'hidden').notifications.send(uids: uids,text: text)

mailru-api

Development