mailru-api 1.0.0.pre → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 69c9fc8530988ef680533c17e96390d73bdefcc1
-  data.tar.gz: 878f132c2290585fe5eb82e13ba9ed342d870f4c
+  metadata.gz: 294bf8eaf893af56dd8f04e36a2393311872b21e
+  data.tar.gz: 135ce3c89736e3a9bdf902fbb851a6f6f26c596e
 SHA512:
-  metadata.gz: d2e33108fb5de2f0c800f74ba4d87bc329c148e338cd8ffb428564c4359bb73e8734b3e184fe58798788761ac1c35f46b7dc859124a4f8f230a81bda1519a63b
-  data.tar.gz: 144fb0b1862eb613c5c7e2d3d6dc2fd1d18d787359ac25d737aafa588e6d0d011fa8646a6ff464e9c271f415f842580ccdde58cf769c87d37199d9951ec2dff9
+  metadata.gz: 46df139e9ccbd0c09a66469ded2491d0ce070014e1c2ba46832fa780bcfd18cd7ae01e900b4c6f01ae1e0889bdf35c37148a373c4d7055e8dc7a89a5b7d4d851
+  data.tar.gz: 851587dc9280e312df7595e6c8d3036f7f2d6fff98c2070fad120b25baa20cc3bff68fca7d14a68a10e8704febf9473bf691d284a8da6780b55f071e0247692e

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Alexey Demin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,173 @@
+[![Gem Version](https://badge.fury.io/rb/mailru-api.png)](http://badge.fury.io/rb/mailru-api) [![Build Status](https://secure.travis-ci.org/ademin/mailru-api.png)](http://travis-ci.org/ademin/mailru-api) [![Code Climate](https://codeclimate.com/github/ademin/mailru-api.png)](https://codeclimate.com/github/ademin/mailru-api) [![Coverage Status](https://coveralls.io/repos/ademin/mailru-api/badge.png)](https://coveralls.io/r/ademin/mailru-api) [![Dependency Status](https://gemnasium.com/ademin/mailru-api.png)](https://gemnasium.com/ademin/mailru-api)
+
+***
+
+# 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'
+
+# Документация
+
+* [Конфигурация](#Конфигурация-api)
+* [Вызов методов @MAIL.RU](#Вызов-методов-mailru)
+* [Обработка результатов вызова](#Обработка-результатов-вызова)
+* [Примеры из реальной жизни](#Примеры-из-реальной-жизни)
+
+
+## Конфигурация API
+
+Перед тем как начать непосредственно вызывать методы @MAIL.RU, нужно создать и сконфигурировать API. Существуют несколько методов конфигурации:
+
+1. Через 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
+
+2. Через конфигурирование в блоке
+
+        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
+
+3. Через параметры конструктора
+
+        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'
+        )
+
+4. Путем комбинирования несколько методов конфигурации:
+
+        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
+
+5. Путем обычной установки параметров
+
+        api = MailRU::API.new
+        app.app_id = 'your app id is here'
+        app.secret_key = 'your secret key is here'
+        ...
+
+### Поддерживаемые параметры конфигурации:
+
+<table>
+  <tr><td>app_id</td><td>Идентификатор приложения</td></tr>
+  <tr><td>secret_key</td><td>Значение secret_key из настроек приложения</td></tr>
+  <tr><td>private_key</td><td>Значение private_key из настроек приложения</td></tr>
+  <tr><td>uid</td><td>Идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key</td></tr>
+  <tr><td>session_key</td><td>Сессия текущего пользователя</td></tr>
+  <tr><td>format</td><td>Формат ответа API; возможные значения: MailRU::API::Format::XML или MailRU::API::Format::JSON (по-умолчанию)</td></tr>
+</table>
+
+Более подробную информацию можно найти по ссылке 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)
+
+# License
+
+Copyright &#169; 2013 Alexey Demin, MIT License

data/lib/mailru/api/dsl.rb

@@ -10,7 +10,7 @@ module MailRU
       def api name, method = :get, secure = Request::Secure::Any
         raise Error.create(0, 'HTTP method must be GET or POST!') unless [:get, :post].include?(method)
 
-        method(SEND).call(:define_singleton_method, underscore(name)) do |params = {}|
+        __send__(:define_singleton_method, underscore(name)) do |params = {}|
           return @api.get("#{@group}.#{name}", params, secure) if method == :get
           return @api.post("#{@group}.#{name}", params, secure) if method == :post
         end
@@ -18,9 +18,6 @@ module MailRU
 
       private
 
-      SEND = (0...6).map{ (65 + rand(26)).chr }.join
-      alias_method(SEND, :send)
-
       def underscore s
         s.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
           gsub(/([a-z\d])([A-Z])/,'\1_\2').

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailru-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexey Demin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-16 00:00:00.000000000 Z
+date: 2013-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -78,7 +78,9 @@ files:
 - lib/mailru/api/format.rb
 - lib/mailru/api/request.rb
 - lib/mailru/api/dsl.rb
-homepage: https://github.com/ademin/mailru
+- LICENSE
+- README.md
+homepage: https://github.com/ademin/mailru-api
 licenses:
 - MIT
 metadata: {}
@@ -93,9 +95,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.3