instagram_api_client 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 887baccb0b7d3120a0ee92699dcd921b4c570b72
-  data.tar.gz: 814b97dfe0ed9fa03a0288083eca1d9ab40d3619
+  metadata.gz: 81a47ca968185f59f026e8a94c53b563785690b6
+  data.tar.gz: 53001d4edc04cd9792ac2e9bd01be53aa91bd7bc
 SHA512:
-  metadata.gz: 4914cbf47863676d499ed7cc7373cab55fef640358d0d2c6abcca69112d7459a639557cb0e1a711f23cdce7cc6249d51b6925c27704d03635f0330a5b107e582
-  data.tar.gz: bf86c1804a3e89fe4028413354dd88d303f811746bcdd6954e1deed75b2ab38d520051917ff29fb60b6e4b79045a8f4ae46b4f3ca94763881915de9cf0e2997f
+  metadata.gz: 2533fde187b43df7de27957e4e8bd03c2734f75a2c9ca0924842ca4e08365726cd54411bf0ef666456e028165341b3103150557a25ced7842220aadfd3d3a719
+  data.tar.gz: 5e04b6862a578e6c6f82b6fd24f17a80e63c9276e020898a16f80b45d55e8fbfa84e99a93ee8d357ffe1ca6037312e1a83891a41b7e356b646a3fa1151138f4c

data/README.md

@@ -1,24 +1,54 @@
-[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/agilie/instagram_api_gem)
+<p align="center">
+  <img width="600" src="https://agilie.com/instagram_api_gem_logo.png" alt="Logo">
+  <img width="100" src="https://agilie.com/logos.png" alt="Logos">
+</p>
+
+<p align="center">
+
+<a href="https://www.agilie.com?utm_source=github&utm_medium=referral&utm_campaign=Git_Ruby&utm_term=instagram_api_gem">
+<img src="https://img.shields.io/badge/Made%20by%20Agilie-*****-green.svg?style=flat" alt="Made by Agilie">
+</a>
+
+<a href="https://github.com/agilie/instagram_api_gem">
+  <img src="https://img.shields.io/github/license/mashape/apistatus.svg" alt="License">
+</a>
+
+<a href="https://rubygems.org/gems/instagram_api_client">
+  <img src="http://ruby-gem-downloads-badge.herokuapp.com/instagram_api_client?type=total&color=brightgreen" alt="Downloads">
+</a>
+
+</p>
 
 # InstagramApi
 
-A Ruby wrapper for the Instagram API. 
-You can see the api endpoints here https://www.instagram.com/developer/endpoints/
+<p align="center"> 
+    <img width="300" src="https://agilie.com/instagram_api_gem.png" alt="Example">
+</p>
+A Ruby wrapper for the Instagram API. You can see the api endpoints here https://www.instagram.com/developer/endpoints/
 
 ## Installation
 
+Install gem in your ruby project
 ```ruby
 gem install instagram_api_client
+```  
+
+or just add to it your `Gemfile`
+```
+gem 'instagram_api_client'
 ```
+if you are on the Rails and run `bundle`
 
 ## Usage
 
 Before you start making the requests to instagram API provide the `access_token` using the configuration
-wrapping.
+wrapping. If you are going to use **Subscriptions** you should add client_id and client_secret.
 
 ```ruby
-InstagramAPI.config do |config|
-  config.access_token = 'put_your_token_here'
+InstagramApi.config do |config|
+  config.access_token = 'put your token here'
+  config.client_id = 'put your client ID here'
+  config.client_secret = 'put your client secret here'
 end
 ```
 
@@ -26,65 +56,133 @@ As for now Instagram access token doesn't change or expire, so you can use this
 to generate it http://services.chrisriversdesign.com/instagram-token/
 I the nearest future the OAuth authorization for access token fetching will be implemented.
 
-The main module of the gem is `InstagramAPI`. It provides a series of methods, regarding each Instagram resource. They are: 
-`Users`, `Media`, `Comments`, `Likes`, `Tags` and `Locations`. So the `Users` resource methods can be accessed by `InstagramAPI.user`
-method, `Tags` by `InstagramAPI.tag` and so on.
+## Resources
+
+The main module of the gem is `InstagramApi`. It provides a series of methods, regarding each Instagram resource. They are: 
+`Users`, `Media`, `Comments`, `Likes`, `Tags` and `Locations`. So the `Users` resource methods can be accessed by `InstagramApi.user`
+method, `Tags` by `InstagramApi.tag` and so on.
 
 The main methods of each resource are `show`, `index`, `create`, `destroy` and `search`. The methods and API endpoints 
 correspondence is as follows 
 
- |    |    | 
+ |  Gem Action  |  API Endpoint  | 
  | -------- | ----- | 
  |  **User Resource** |  | 
- |  InstagramAPI.user.show | GET /users/self | 
- |  InstagramAPI.user(**user_id**).show | GET /users/**user_id** | 
- |  InstagramAPI.user.recent_media | GET /users/self/media/recent | 
- |  InstagramAPI.user(**user_id**).recent_media | GET /users/**user_id**/media/recent | 
- |  InstagramAPI.user.liked_media | GET /users/self/media/liked | 
- |  InstagramAPI.user.search(**search_query**) | GET /users/search | 
+ |  InstagramApi.user.show | GET /users/self | 
+ |  InstagramApi.user(**user_id**).show | GET /users/**user_id** | 
+ |  InstagramApi.user.recent_media | GET /users/self/media/recent | 
+ |  InstagramApi.user(**user_id**).recent_media | GET /users/**user_id**/media/recent | 
+ |  InstagramApi.user.liked_media | GET /users/self/media/liked | 
+ |  InstagramApi.user.search(**search_query**) | GET /users/search | 
  |  *Relationship Endpoints block* |  | 
- |  InstagramAPI.user.follows | GET /users/self/follows | 
- |  InstagramAPI.user.followed_by | GET /users/self/followed-by | 
- |  InstagramAPI.user.requested_by | GET /users/self/requested-by | 
- |  InstagramAPI.user.check_relationship(**user_id**) | GET /users/**user_id**/relathionship | 
- |  InstagramAPI.user.change_relationship(**user_id**) | POST /users/**user_id**/relathionship | 
+ |  InstagramApi.user.follows | GET /users/self/follows | 
+ |  InstagramApi.user.followed_by | GET /users/self/followed-by | 
+ |  InstagramApi.user.requested_by | GET /users/self/requested-by | 
+ |  InstagramApi.user.check_relationship(**user_id**) | GET /users/**user_id**/relathionship | 
+ |  InstagramApi.user.change_relationship(**user_id**) | POST /users/**user_id**/relathionship | 
  |  **Media Resource** |  | 
- |  InstagramAPI.media(**media_id**).show | GET /media/**media_id** | 
- |  InstagramAPI.media.short_code(**short_code**) | GET /media/shortcode/**shortcode** | 
- |  InstagramAPI.media.search(**search_query**) | GET /media/search | 
+ |  InstagramApi.media(**media_id**).show | GET /media/**media_id** | 
+ |  InstagramApi.media.short_code(**short_code**) | GET /media/shortcode/**shortcode** | 
+ |  InstagramApi.media.search(**search_query**) | GET /media/search | 
  |  *Likes Endpoints block* |  | 
- |  InstagramAPI.media(media_id).likes | GET /media/**media_id**/likes | 
- |  InstagramAPI.media(media_id).add_like | POST /media/**media_id**/likes | 
- |  InstagramAPI.media(media_id).delete_like | DELETE /media/**media_id**/likes | 
+ |  InstagramApi.media(media_id).likes | GET /media/**media_id**/likes | 
+ |  InstagramApi.media(media_id).add_like | POST /media/**media_id**/likes | 
+ |  InstagramApi.media(media_id).delete_like | DELETE /media/**media_id**/likes | 
  |  *Comment Endpoints block* |  | 
- |  InstagramAPI.media(media_id).comments | GET /media/**media_id**/comments | 
- |  InstagramAPI.media(media_id).add_comment | POST /media/**media_id**/comments | 
- |  InstagramAPI.media(media_id).delete_comment(**comment_id**) | DELETE /media/**media_id**/comments/**comment_id** | 
+ |  InstagramApi.media(media_id).comments | GET /media/**media_id**/comments | 
+ |  InstagramApi.media(media_id).add_comment | POST /media/**media_id**/comments | 
+ |  InstagramApi.media(media_id).delete_comment(**comment_id**) | DELETE /media/**media_id**/comments/**comment_id** | 
  |  **Tag Resource** |  | 
- |  InstagramAPI.tag(**tag_name**).show | GET /tags/**tag_name** | 
- |  InstagramAPI.tag(**tag_name**).recent_media | GET /tags/**tag_name**/media/recent | 
- |  InstagramAPI.tag.search(**search_query**) | GET /tags/search | 
+ |  InstagramApi.tag(**tag_name**).show | GET /tags/**tag_name** | 
+ |  InstagramApi.tag(**tag_name**).recent_media | GET /tags/**tag_name**/media/recent | 
+ |  InstagramApi.tag.search(**search_query**) | GET /tags/search | 
  |  **Location Resource** |  | 
- |  InstagramAPI.location(**location_id**).show | GET /locations/**location_id** | 
- |  InstagramAPI.location(**location_id**).recent_media | GET /locations/**location_id**/media/recent | 
- |  InstagramAPI.location.search(**search_query**) | GET /locations/search | 
+ |  InstagramApi.location(**location_id**).show | GET /locations/**location_id** | 
+ |  InstagramApi.location(**location_id**).recent_media | GET /locations/**location_id**/media/recent | 
+ |  InstagramApi.location.search(**search_query**) | GET /locations/search | 
 
 Each method from the list above accepts a hash as a second argument with additional params according to official 
 [instagram developers documentation](https://www.instagram.com/developer/endpoints/) i.e.
 
 ```ruby
-InstagramAPI.user.search('mell', {count: 10})
-InstagramAPI.user('my_user_id').recent_media({min_id: '22721881'})
+InstagramApi.user.search('mell', {count: 10})
+InstagramApi.user('my_user_id').recent_media({min_id: '22721881'})
 ```
 
 Search method can get either a query string or a hash. It depends on API requirements, i.e.
 ```ruby
-InstagramAPI.user.search('mell')
-InstagramAPI.location.search({lat: 33.10, lng: 15.40})
+InstagramApi.user.search('mell')
+InstagramApi.location.search({lat: 33.10, lng: 15.40})
 ```
 
 Response is a `Hashie::Mash` object
 
+## Subscriptions
+
+Subscriptions is a useful feature which allows to receive notifications when people who authenticated your app
+post new media on Instagram. You can find more information on https://www.instagram.com/developer/subscriptions/
+
+#### Creating a subscription
+
+Creating subscription is very simple. Just refer to the [original documentation](https://www.instagram.com/developer/subscriptions/) to
+check the options available
+```ruby
+InstagramApi.subscription.create({
+    object: 'user',
+    aspect: 'media',
+    callback_url: 'http://your.callback/url'
+})
+```
+This method automatically generates `verify_token`. However, you can pass your own, if you prefer
+```ruby
+InstagramApi.subscription.create({
+    object: 'user',
+    aspect: 'media',
+    callback_url: 'http://your.callback/url',
+    verify_token: 'MyCustomVerifyToken'
+})
+```
+#### Validating subscription
+
+When you add a subscription, Instagram will send a GET request to your callback URL to verify the existence of the URL.
+When Instagram has new data, it'll POST this data to your callback URL. To validate the subscription your callback action
+should validate verify_token from instagram request and response with a `hub.challenge` parameter value.
+
+You can easily implement it with a single line
+
+```ruby
+# CallbackController
+
+# GET callback url action
+def index
+    render plain: InstagramApi.subscription.validate(params)
+end
+```
+or
+```ruby
+# CallbackController
+
+# GET callback url action
+def index
+    render plain: InstagramApi.subscription.validate(params, 'MyCustomVerifyToken')
+end
+```
+if you are using your own `verify_token`
+
+#### Managing subscriptions
+
+You can easily get the list of your subscriptions
+```ruby
+InstagramApi.subscription.index
+```
+
+or destroy them if you prefer
+
+```ruby
+InstagramApi.subscription.destroy({object: 'all'})
+InstagramApi.subscription.destroy({id: 1})
+```
+
 
 ## TODOS
 

data/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

data/lib/instagram_api.rb

@@ -9,10 +9,12 @@ require 'instagram_api/location'
 require 'instagram_api/media'
 require 'instagram_api/configuration'
 
+require 'instagram_api/subscription'
+
 module InstagramApi
   extend Configuration
 
-  RESOURCES = %w(user location tag media).freeze
+  RESOURCES = %w(user location tag media subscription).freeze
 
   class << self
     RESOURCES.each do |resource|

data/lib/instagram_api/configuration.rb

@@ -2,6 +2,8 @@ module InstagramApi
   module Configuration
 
     OPTIONS = [
+      :client_id,
+      :client_secret,
       :access_token
     ].freeze
 

data/lib/instagram_api/exceptions.rb

@@ -1,5 +1,6 @@
 module InstagramApi
 
+  # Custom error class to rescue from Instagram errors
   class Error < StandardError
     attr_reader :message, :type, :code
 

data/lib/instagram_api/subscription.rb

@@ -0,0 +1,66 @@
+require 'instagram_api/common'
+
+module InstagramApi
+
+  class Subscription
+
+    include Client
+
+    def initialize(fake_param = nil)
+      @client_id = InstagramApi.client_id
+      @client_secret = InstagramApi.client_secret
+      raise 'Invalid configuration: client ID is missing' unless @client_id
+      raise 'Invalid configuration: client secret is missing' unless @client_secret
+    end
+
+    def create(options)
+      @@verify_token = options[:verify_token] || generate_verify_token
+      options = {
+        client_id: @client_id,
+        client_secret: @client_secret,
+        verify_token: @@verify_token,
+      }.merge(options)
+      make_request resource_path,
+                   { body: options },
+                   :post
+    end
+
+    def index
+      options = {
+        client_id: @client_id,
+        client_secret: @client_secret
+      }
+      make_request resource_path,
+                   { query: options }
+    end
+
+    def destroy(options)
+      options = {
+        client_id: @client_id,
+        client_secret: @client_secret
+      }.merge(options)
+      make_request resource_path,
+                   { query: options },
+                   :delete
+    end
+
+    def validate(params, verify_token = nil)
+      verify_token = verify_token || @@verify_token
+      return unless params['hub.mode'] == 'subscribe' || params['hub.verify_token'] == verify_token
+      params['hub.challenge']
+    end
+
+    private
+
+    def generate_verify_token
+      ['a'..'z', 'A'..'Z', 0..9].map(&:to_a).flatten.sample(16).join
+    end
+
+    def resource_path
+      "#{BASE_API_URI}/subscriptions"
+    end
+
+  end
+
+end
+

data/lib/instagram_api/user.rb

@@ -2,14 +2,27 @@ require 'instagram_api/common'
 
 module InstagramApi
 
+  # Defines methods which correspond to User resource
   class User
     include Search
     include Resource
 
+    # User instance constructor. Accepts the +user_id+ or refers to +self+
+
     def initialize(user_id)
       @user_id = user_id || 'self'
     end
 
+    # Returns an information about the given user
+    #
+    # @overload show(options={})
+    #   @return [Hashie::Mash] The requested user.
+    #   @example Return extended information for @shayne
+    #     Instagram.user(20)
+    # @format :json
+    # @rate_limited true
+    # @see https://www.instagram.com/developer/endpoints/users/#get_users
+    # @see https://www.instagram.com/developer/endpoints/users/#get_users_self
     def show(options = {})
       super @user_id, options
     end
@@ -39,7 +52,7 @@ module InstagramApi
     end
 
     def change_relationship(user_id, options = {})
-      make_request resource_path("#{user_id}/relationship"), {body: options}, :post
+      make_request resource_path("#{user_id}/relationship"), { body: options }, :post
     end
   end
 

data/lib/instagram_api/version.rb

@@ -1,3 +1,3 @@
 module InstagramApi
-  VERSION = '0.1.1'
+  VERSION = '0.2.1'
 end

data/lib/instagram_api_client.rb

@@ -0,0 +1 @@
+require 'instagram_api'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: instagram_api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Sergey Mell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-05 00:00:00.000000000 Z
+date: 2017-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,6 +110,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- _config.yml
 - bin/console
 - bin/setup
 - instagram_api.gemspec
@@ -120,9 +121,11 @@ files:
 - lib/instagram_api/exceptions.rb
 - lib/instagram_api/location.rb
 - lib/instagram_api/media.rb
+- lib/instagram_api/subscription.rb
 - lib/instagram_api/tag.rb
 - lib/instagram_api/user.rb
 - lib/instagram_api/version.rb
+- lib/instagram_api_client.rb
 homepage: https://github.com/agilie/instagram_api_gem
 licenses:
 - MIT