angellist_api 1.0.1 → 1.0.2

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## Master
+
+## 1.0.2 - 30 July, 2012
+
+- Loosen dependency requirements for faraday and multi_json, so we don't
+  conflict with newer versions of other API gems like Twitter.
+- Added available batch endpoints (users, startups, follows).
+- Added jobs endpoints.
+- Added search endpoint.
+- Filled in a few gaps: startup comments and single activity feed item
+  endpoints.
+- Integration specs added using VCR, for unauthenticated calls so far.
+- Backported several changes from Twitter gem which was our genesis.
+- YARD cleanup.
+
 ## 1.0.1 - 22 March, 2012
 
 - Doh, we bungled a version number -- no changes.

data/README.md

@@ -1,22 +1,27 @@
 # The AngelList API Ruby Gem
 
-A Ruby wrapper for the [AngelList REST APIs][].
+A Ruby wrapper for the [AngelList REST APIs][]. See the [YARD documentation][].
 
-## <a name="installation">Installation</a>
+## Installation
 
     gem install angellist_api
 
-## <a name="pulls">Submitting a Pull Request</a>
+## Submitting a Pull Request
 
 1. Fork the project.
 2. Create a topic branch.
 3. Implement your feature or bug fix.
 4. Add documentation for your feature or bug fix.
-5. Run <tt>bundle exec rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
+5. Run <tt>bundle exec rake doc:yard</tt>. If your changes are not 100%
+   documented, go back to step 4.
 6. Add specs for your feature or bug fix.
-7. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go back to step 6.
+7. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go
+   back to step 6.
 8. Commit and push your changes.
-9. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+9. Submit a pull request. Please do not include changes to the gemspec,
+   version, or history file. (If you want to create your own version for some
+   reason, please do so in a separate commit.)
 
 [AngelList REST APIs]: http://angel.co/api
+[YARD documentation]: http://rdoc.info/gems/angellist_api/frames
 

data/Rakefile

@@ -14,6 +14,15 @@ RSpec::Core::RakeTask.new(:spec)
 task :test => :spec
 task :default => :spec
 
+namespace :spec do
+  [:integration, :unit].each do |type|
+    desc "Run the code examples in spec/#{type}"
+    RSpec::Core::RakeTask.new(type) do |t|
+      t.pattern = "./spec/#{type}/**/*_spec.rb"
+    end
+  end
+end
+
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb', 'README.md']
 end

data/lib/angellist_api.rb

@@ -1,7 +1,5 @@
-require 'angellist_api/api'
 require 'angellist_api/client'
 require 'angellist_api/configuration'
-require 'angellist_api/error'
 
 module AngellistApi
   extend Configuration
@@ -23,4 +21,4 @@ module AngellistApi
       new.respond_to?(method, include_private) || super(method, include_private)
     end
   end
-end
+end

data/lib/angellist_api/api.rb

@@ -4,13 +4,11 @@ require 'angellist_api/connection'
 require 'angellist_api/request'
 
 module AngellistApi
-  # @private
   class API
+    include Authentication
     include Connection
     include Request
-    include Authentication
 
-    # @private
     attr_accessor *Configuration::VALID_OPTIONS_KEYS
 
     # Creates a new API
@@ -21,4 +19,4 @@ module AngellistApi
       end
     end
   end
-end
+end

data/lib/angellist_api/authentication.rb

@@ -1,5 +1,4 @@
 module AngellistApi
-  # @private
   module Authentication
     private
 

data/lib/angellist_api/client.rb

@@ -1,14 +1,20 @@
+require 'cgi'
+require 'angellist_api/api'
+
 module AngellistApi
   # Wrapper for the AngellistApi REST API
   #
-  # @note All methods have been separated into modules and follow the same grouping used in {http://angel.co/api the Angellist API Documentation}.
+  # @note All methods have been separated into modules and follow the same
+  #   grouping used in {http://angel.co/api the Angellist API Documentation}.
   class Client < API
     # Require client method modules after initializing the Client class in
     # order to avoid a superclass mismatch error, allowing those modules to be
     # Client-namespaced.
     require 'angellist_api/client/activity_feeds'
     require 'angellist_api/client/follows'
+    require 'angellist_api/client/jobs'
     require 'angellist_api/client/reviews'
+    require 'angellist_api/client/search'
     require 'angellist_api/client/startups'
     require 'angellist_api/client/startup_roles'
     require 'angellist_api/client/status_updates'
@@ -19,7 +25,9 @@ module AngellistApi
 
     include AngellistApi::Client::ActivityFeeds
     include AngellistApi::Client::Follows
+    include AngellistApi::Client::Jobs
     include AngellistApi::Client::Reviews
+    include AngellistApi::Client::Search
     include AngellistApi::Client::Startups
     include AngellistApi::Client::StartupRoles
     include AngellistApi::Client::StatusUpdates

data/lib/angellist_api/client/activity_feeds.rb

@@ -1,19 +1,40 @@
 module AngellistApi
   class Client
     # Defines methods related to URLs
+    #
+    # @see http://angel.co/api/spec/activity_feeds
     module ActivityFeeds
-      
-      # Returns site activity. If authenticated and the personalized parameter is passed in, only activity from the authenticated user's social graph is returned. No more than 25 items will be returned. Results are paginated and ordered by most recent story first.
+
+      # Returns site activity. If authenticated and the personalized parameter
+      # is passed in, only activity from the authenticated user's social graph
+      # is returned. No more than 25 items will be returned. Results are
+      # paginated and ordered by most recent story first.
+      #
       # @requires_authentication Optional
-      # @response_format `json`
+      #
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :personalized If set to 1 and a user is authenticated, only activity from the authenticated user's social graph is returned.
-      # @example 
+      # @option options [Integer] :personalized If set to 1 and a user is
+      #   authenticated, only activity from the authenticated user's social graph
+      #   is returned.
+      #
+      # @example
       #   AngellistApi.get_feed
       def get_feed(options={})
-        get("1/feed", options, :format => :json, :phoenix => true)
+        get("1/feed", options)
+      end
+
+      # Returns a specific activity feed item.
+      #
+      # @requires_authentication No
+      #
+      # @param id [String] String ID of the feed item to retrieve.
+      #
+      # @example Get a feed item.
+      #   AngellistApi.feed_item('8fCC3')
+      def feed_item(id)
+        get("1/feed/#{id}")
       end
-      
     end
   end
-end
+end
+

data/lib/angellist_api/client/follows.rb

@@ -1,96 +1,138 @@
 module AngellistApi
   class Client
     # Defines methods related to URLs
+    #
+    # @see http://angel.co/api/spec/follows
     module Follows
-      # Makes the authenticated user follow the specified item. Returns the new follow on success, or an error on failure.
+      # Makes the authenticated user follow the specified item. Returns the new
+      # follow on success, or an error on failure.
+      #
       # @requires_authentication Yes
-      # @response_format `json`
-      # @param options [Hash] A customizable set of options.
-      # @option options [String] :type Must be either user or startup. 
+      #
+      # @param [Hash] options A customizable set of options.
+      # @option options [String] :type Must be either user or startup.
       # @option options [Integer] :id The id of the user or startup to start following.
-      # @example Makes the authenticated user follow the specified item. Returns the new follow on success, or an error on failure.
-      #   AngellistApi.new_follow
+      #
+      # @example Follow a startup with the authenticated user.
+      #   AngellistApi.new_follow(:type => :startup, :id => 12345)
       def new_follow(options={})
-        post("1/follows", options, :format => :json, :phoenix => true)
+        post("1/follows", options)
       end
-      
-      # Makes the authenticated user stop following the specified item. Returns the deleted follow on success, or an error on failure.
+
+      # Makes the authenticated user stop following the specified item. Returns
+      # the deleted follow on success, or an error on failure.
+      #
       # @requires_authentication Yes
-      # @response_format `json`
-      # @param options [Hash] A customizable set of options.
-      # @option options [String] :type Must be either user or startup. 
+      #
+      # @param [Hash] options A customizable set of options.
+      # @option options [String] :type Must be either user or startup.
       # @option options [Integer] :id The id of the user or startup to start following.
-      # @example Makes the authenticated user stop following the specified item. Returns the deleted follow on success, or an error on failure.
-      #   AngellistApi.delete_follow
+      #
+      # @example Make the authenticated user stop following a startup.
+      #   AngellistApi.delete_follow(:type => :startup, :id => 12345)
       def delete_follow(options={})
-        delete("1/follows", options, :format => :json, :phoenix => true)
+        delete("1/follows", options)
       end
-      
-      # Return the given user's followers, paginated and ordered by most recent follower first.
+
+      # Returns the follower and followed information based on comma-separated
+      # follow ids, such as those from the activity feed.
+      #
+      # @requires_authentication Optional
+      #
+      # @param ids [Array] IDs of the follows to fetch.
+      #
+      # @example Get follower and followed information for a batch of follows.
+      #   AngellistApi.get_follows([1, 2, 3])
+      def get_follows(ids)
+        params = { :ids => ids.join(',') }
+        get("1/follows/batch", params)
+      end
+
+      # Return the given user's followers, paginated and ordered by most recent
+      # follower first.
+      #
       # @requires_authentication No
-      # @response_format `json`
-      # @param options [Integer] The id of the given user.
-      # @example Return the given user's followers, paginated and ordered by most recent follower first.
-      #   AngellistApi.get_user_followers
+      #
+      # @param [Integer] id The id of the given user.
+      #
+      # @example Get followers of user with ID 12345.
+      #   AngellistApi.get_user_followers(12345)
       def get_user_followers(id)
-        get("1/users/#{id}/followers", :format => :json, :phoenix => true)
+        get("1/users/#{id}/followers")
       end
-      
-      # Return the ids of the given user's followers, paginated and ordered by most recent follower first.
+
+      # Return the ids of the given user's followers, paginated and ordered by
+      # most recent follower first.
+      #
       # @requires_authentication No
-      # @response_format `json`
-      # @param options [Integer] The id of the given user.
-      # @example Return the ids of the given user's followers, paginated and ordered by most recent follower first.
-      #   AngellistApi.get_user_follower_ids
+      #
+      # @param [Integer] id The id of the given user.
+      #
+      # @example Get IDs of the followers of user with ID 12345.
+      #   AngellistApi.get_user_follower_ids(12345)
       def get_user_follower_ids(id)
-        get("1/users/#{id}/followers/ids", :format => :json, :phoenix => true)
+        get("1/users/#{id}/followers/ids")
       end
-      
-      # Return objects that the given user is following, paginated and ordered by most recent follow first. See the type parameter to specify which class of objects to return.
+
+      # Return objects that the given user is following, paginated and ordered
+      # by most recent follow first. See the type parameter to specify which
+      # class of objects to return.
+      #
       # @requires_authentication Optional
-      # @response_format `json`
-      # @param id [Integer] The id of the given user.
-      # @param options [Hash] A customizable set of options.
-      # @option options [String] :type Must be either user or startup. 
-      # @example Return objects that the given user is following, paginated and ordered by most recent follow first. See the type parameter to specify which class of objects to return.
-      #   AngellistApi.get_user_following
+      #
+      # @param [Integer] id The id of the given user.
+      # @param [Hash] options A customizable set of options.
+      # @option options [String] :type ('user') Must be either user or startup.
+      #
+      # @example Get startups that user with ID 1234 is following.
+      #   AngellistApi.get_user_following(1234, :type => :startup)
       def get_user_following(id, options={})
-        get("1/users/#{id}/following", options, :format => :json, :phoenix => true)
+        get("1/users/#{id}/following", options)
       end
-      
-      # Return ids of objects that the given user is following, paginated and ordered by most recent follow first. See the type parameter to specify which class of objects to return. Responds like GET /users/:id/followers/ids.
+
+      # Return ids of objects that the given user is following, paginated and
+      # ordered by most recent follow first. See the type parameter to specify
+      # which class of objects to return. Responds like GET
+      # /users/:id/followers/ids.
+      #
       # @requires_authentication Optional
-      # @response_format `json`
-      # @param id [Integer] The id of the given user.
-      # @param options [Hash] A customizable set of options.
-      # @option options [String] :type Must be either user or startup. 
-      # @example Return ids of objects that the given user is following, paginated and ordered by most recent follow first. See the type parameter to specify which class of objects to return. Responds like GET /users/:id/followers/ids.
-      #   AngellistApi.get_user_following_ids
+      #
+      # @param [Integer] id The id of the given user.
+      # @param [Hash] options A customizable set of options.
+      # @option options [String] :type ('user') Must be either user or startup.
+      #
+      # @example Get IDs of startups that user with ID 1234 is following.
+      #   AngellistApi.get_user_following_ids(1234, :type => :startup)
       def get_user_following_ids(id, options={})
-        get("1/users/#{id}/following/ids", options, :format => :json, :phoenix => true)
+        get("1/users/#{id}/following/ids", options)
       end
-      
-      # Returns the given startup's followers, paginated and ordered by most recent follower first. Responds like GET /users/:id/followers.
+
+      # Returns the given startup's followers, paginated and ordered by most
+      # recent follower first. Responds like GET /users/:id/followers.
+      #
       # @requires_authentication Optional
-      # @response_format `json`
-      # @param id [Integer] The id of the given user.
-      # @param options [Hash] A customizable set of options.
-      # @example Returns the given startup's followers, paginated and ordered by most recent follower first. Responds like GET /users/:id/followers.
-      #   AngellistApi.get_startup_followers
+      #
+      # @param [Integer] id The id of the given startup.
+      #
+      # @example Get followers of startup with ID 1234.
+      #   AngellistApi.get_startup_followers(1234)
       def get_startup_followers(id)
-        get("1/startups/#{id}/followers", :format => :json, :phoenix => true)
+        get("1/startups/#{id}/followers")
       end
-      
-      # Returns the ids of the given startup's followers, paginated and ordered by most recent follower first. Responds like GET /users/:id/followers.
+
+      # Returns the ids of the given startup's followers, paginated and ordered
+      # by most recent follower first. Responds like GET /users/:id/followers.
+      #
       # @requires_authentication Optional
-      # @response_format `json`
-      # @param id [Integer] The id of the given user.
-      # @param options [Hash] A customizable set of options.
-      # @example Returns the ids of the given startup's followers, paginated and ordered by most recent follower first. Responds like GET /users/:id/followers.
-      #   AngellistApi.get_startup_follower_ids
+      #
+      # @param [Integer] id The id of the given user.
+      #
+      # @example Get IDs of followers of startup with ID 1234.
+      #   AngellistApi.get_startup_follower_ids(1234)
       def get_startup_follower_ids(id)
-        get("1/startups/#{id}/followers/ids", :format => :json, :phoenix => true)
+        get("1/startups/#{id}/followers/ids")
       end
     end
   end
 end
+

data/lib/angellist_api/client/jobs.rb

@@ -0,0 +1,72 @@
+module AngellistApi
+  class Client
+    # Defines methods related to URLs
+    #
+    # @see http://angel.co/api/spec/jobs
+    module Jobs
+
+      # Returns all jobs that have been posted. Results are paginated and
+      # ordered by publish date descending.
+      #
+      # @requires_authentication No
+      # @paginated Yes
+      #
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :page Specifies the page of results to
+      #   retrieve.
+      # @option options [Integer] :per_page (50) The number of results to return
+      #   for a page. Maximum of 50.
+      #
+      # @note Pagination metadata does not actually appear to be returned
+      #   currently, but the page parameter works. Have inquired with AngelList
+      #   about this.
+      def get_jobs(options={})
+        get("1/jobs", options)
+      end
+
+      # Shows details for a specific job, including the startup that posted it.
+      #
+      # @requires_authentication No
+      #
+      # @param id [Integer] ID of the job to fetch.
+      #
+      # @example Get information for a job.
+      #   AngellistApi.get_job(137)
+      def get_job(id)
+        get("1/jobs/#{id}")
+      end
+
+      # For a given startup id, returns all the jobs that have been posted.
+      #
+      # @requires_authentication No
+      # @paginated No
+      #
+      # @param id [Integer] ID of the desired startup.
+      #
+      # @example Get jobs for a given startup by ID.
+      #   AngellistApi.get_startup_jobs(1234)
+      def get_startup_jobs(id)
+        get("1/startups/#{id}/jobs")
+      end
+
+      # For a given LocationTag id, returns all jobs posted in that tag.
+      #
+      # @requires_authentication No
+      # @paginated Yes
+      #
+      # @param id [Integer] ID of the desired tag.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :page Specifies the page of results to
+      #   retrieve.
+      # @option options [Integer] :per_page (50) The number of results to return
+      #   for a page. Maximum of 50.
+      #
+      # @example Get jobs tagged San Francisco.
+      #   AngellistApi.get_tag_jobs(1692)
+      def get_tag_jobs(id, options={})
+        get("1/tags/#{id}/jobs", options)
+      end
+    end
+  end
+end
+