greenhouse_io 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96d09bdfaaaac579b55d887e19e8841464b5c260
-  data.tar.gz: a602434a5d159890c66d409e9ce5b84d0cd3cbba
+  metadata.gz: 9f601eaa22aed7becbf93fd8199fe6e48e9726ac
+  data.tar.gz: a346a9f3404a2029b9120222f443a3e1cc561373
 SHA512:
-  metadata.gz: 6cc57641acc11a17e7dd119cfadecd76a698aec9cd80ddf281a15a84764941f34c0f8ea7c1140c1d9f33aa6a55adad247f52fd77429d85b34f122cc07d9f2731
-  data.tar.gz: 15447a18d502738a6181ce8b7883f10739931fe15fe01466f2430465f655b450ba2db0ba96526e685ff587a036c014fb45ada43d884a4f246d52b3f6332db3ef
+  metadata.gz: 9b7f32c167e8da28dc2590246f774878c33e939aa4a5a3209730d71f53e658790df0dca8a674fd8823eb71045da1ca8d839df912ca99ce8960ed207ee01ab540
+  data.tar.gz: ef43dfc2b60318b96b4ee1795da0c1e5adb7dde1511d392cae24c5c9d5cb963b98c1c3992717bb048e86ee24d82935713a992b2d6dade8851d35ba7269f7d9b3

data/.gitignore

@@ -13,3 +13,4 @@ pkg
 rdoc
 spec/reports
 tmp
+.ruby-*

data/README.md

@@ -12,75 +12,85 @@ API (requires Ruby 1.9.3 or greater).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your application's Gemfile:
 
     gem 'greenhouse_io'
 
-And then execute:
-
-    $ bundle
-
 Or install it yourself as:
 
     $ gem install greenhouse_io
+    
+## Configuration
 
-## Usage
+You can assign default configuration values when using this gem.  
+Here is an example `config/initializers/greenhouse_io.rb` file used in a Rails application:
 
-Creating an instance of the API client:
 ```ruby
-gh = GreenhouseIo::API.new("api_token")
+GreenhouseIo.configure do |config|
+	config.symbolize_keys = true # set response keys as strings or symbols, default is false
+	config.organization = 'General Assembly'
+	config.api_token = ENV['GREENHOUSE_API_TOKEN']
+end
 ```
 
-The client will also use the environment variable `'GREENHOUSE_API_TOKEN'` by default:
+## Usage
+
+Greenhouse's two APIs, **[Harvest](https://app.greenhouse.io/configure/dev_center/harvest)** and **[JobBoard](https://app.greenhouse.io/configure/dev_center/api_documentation)**, can now be accessed through the gem. The [`GreenhouseIo::JobBoard`](#greenhouseiojobboard) is nearly identical to the old `GreenhouseIo::API` class. [`GreenhouseIo::Client`](#greenhouseioclient) connects to the new Harvest API.
+
+### GreenhouseIo::JobBoard
+
+Creating an instance of the JobBoard client:
 ```ruby
-gh = GreenhouseIo::API.new
+gh = GreenhouseIo::JobBoard.new("api_token", organization: "your_organization")
 ```
 
-A default organization can be passed through an options hash:
+If you've configured the gem with a default `organization` and `api_token`, then you can just instantiate the class.
 ```ruby
-gh = GreenhouseIo::API.new("api_token", :organization => "your_organization")
+gh = GreenhouseIo::JobBoard.new
 ```
 
-### Fetching Office Data
+`api_token` is only required for `#apply_to_job` and `organization` is also optional during initialization if an organization is passed in during method requests.
+
+#### Fetching Office Data
 ```ruby
 gh.offices
-gh.offices(:organization => 'different_organization')
+gh.offices(organization: 'different_organization')
 # returns a hash containing all of the organization's department and jobs grouped by office
 ```
 
 ```ruby
-gh.office(officeID)
-gh.office(officeID, :organization => 'different_organization')
+gh.office(id)
+gh.office(id, organization: 'different_organization')
 # returns a hash containing the departments and jobs of a specific office
 ```
 
-### Fetching Department Data
+#### Fetching Department Data
 ```ruby
 gh.departments
-gh.departments(:organization => 'different_organizaton')
+gh.departments(organization: 'different_organizaton')
 ```
 
 ```ruby
-gh.department(departmentID)
-gh.department(departmentID, :organization => 'different_organization')
+gh.department(id)
+gh.department(id, organization: 'different_organization')
 ```
 
-### Fetching Job Data
+#### Fetching Job Data
 ```ruby
 gh.jobs
-gh.jobs(:content => 'true')
+gh.jobs(content: 'true')
 # includes the job description in the response
-gh.jobs(:organization => 'different_organization')
+gh.jobs(organization: 'different_organization')
 ```
 
 ```ruby
-gh.job(jobID)
-gh.job(jobID, :questions => true)
+gh.job(id)
+gh.job(id, questions: true)
 # returns the specified job and the array of questions on the application
-gh.job(jobID, :organization => 'different_organization')
+gh.job(id, organization: 'different_organization')
 ```
 
-### Submitting a Job Application
+#### Submitting a Job Application
 This is the only API method that **requires** an API token from Greenhouse
 ```ruby
 gh.apply_to_job(form_parameter_hash)
@@ -90,6 +100,55 @@ gh.apply_to_job(form_parameter_hash)
 # has the value of the job ID on Greenhouse.io
 ```
 
+### GreenhouseIo::Client
+
+Creating an instance of the API client:
+```ruby
+gh_client = GreenhouseIo::Client.new("api_token")
+```
+
+If you've configured the gem with a default `api_token`, then you can just instantiate the class.
+```ruby
+gh_client = GreenhouseIo::Client.new
+```
+
+#### Throttling
+
+Rate limit and rate limit remaining are availbe fter making an API request with an API client:
+
+```ruby
+gh_client.rate_limit # => 20
+gh_client.rate_limit_remaining  # => 20
+```
+
+#### Pagination
+
+All `GreenhouseIo::Client` API methods accept `:page` and `:per_page` options to get specific results of a paginated response from Greenhouse.
+
+```ruby
+gh_client.offices(id, page: 1, per_page: 2)
+```
+
+#### Available methods
+
+Methods in which an `id` is optional:
+
+* `offices`
+* `departments`
+* `candidates`
+* `applications`
+* `jobs`
+* `users`
+* `sources`
+
+Methods in which an `id` is **required**:
+
+* `activity_feed` *(requires a candidate ID)*
+* `scorecards` *(requires an application ID)*
+* `scheduled_interviews` *(requires an application ID)*
+* `stages` *(requires a job ID)*
+* `job_post` *(requires a job ID)*
+
 ## Contributing
 
 1. Fork it

data/lib/greenhouse_io.rb

@@ -4,4 +4,7 @@ require 'cgi'
 
 require "greenhouse_io/version"
 require "greenhouse_io/error"
+require "greenhouse_io/configuration"
 require "greenhouse_io/api"
+require "greenhouse_io/api/job_board"
+require "greenhouse_io/api/client"

data/lib/greenhouse_io/api.rb

@@ -1,72 +1,19 @@
 module GreenhouseIo
-  class API
-    attr_accessor :api_token, :organization
-
-    include HTTMultiParty
-    base_uri 'https://api.greenhouse.io/v1'
-
-    def initialize(api_token = nil, default_options = {})
-      @api_token = api_token || ENV['GREENHOUSE_API_TOKEN']
-      @organization = default_options.delete(:organization)
-    end
-
-    def offices(options = {})
-      get_response_hash("/boards/#{ query_organization(options) }/embed/offices")
-    end
-
-    def office(id, options = {})
-      get_response_hash("/boards/#{ query_organization(options) }/embed/office?id=#{ id }")
-    end
-
-    def departments(options = {})
-      get_response_hash("/boards/#{ query_organization(options) }/embed/departments")
-    end
-
-    def department(id, options = {})
-      get_response_hash("/boards/#{ query_organization(options) }/embed/department?id=#{ id }")
+  module API
+    def get_response(url, options)
+      self.class.get(url, options)
     end
 
-    def jobs(options = {})
-      get_response_hash("/boards/#{ query_organization(options) }/embed/jobs?content=#{ options[:content] }")
+    def post_response(url, options)
+      self.class.post(url, options)
     end
 
-    def job(id, options = { :questions => false })
-      get_response_hash("/boards/#{ query_organization(options) }/embed/job?id=#{ id }&questions=#{ options[:questions] }")
-    end
-
-    def apply_to_job(job_form_hash)
-      options = { :body => job_form_hash, :basic_auth => basic_auth }
-      post_response_hash('/applications', options)
-    end
-
-    private
-
-    def query_organization(options_hash)
-      org = options_hash[:organization] || @organization
-      org.nil? ? (raise GreenhouseIo::Error.new("organization can't be blank")) : org
-    end
-
-    def get_response_hash(url)
-      response = self.class.get(url)
-      if response.code == 200
-        MultiJson.load(response.body, :symbolize_keys => true)
-      else
-        raise GreenhouseIo::Error.new(response.code)
-      end
-    end
-
-    def post_response_hash(url, options)
-      response = self.class.post(url, options)
-      if response.code == 200
-        response.include?("success") ? MultiJson.load(response.body, :symbolize_keys => true) : raise(GreenhouseIo::Error.new(response["reason"]))
-      else
-        raise GreenhouseIo::Error.new(response.code)
-      end
+    def parse_json(response)
+      MultiJson.load(response.body, symbolize_keys: GreenhouseIo.configuration.symbolize_keys)
     end
 
     def basic_auth
-      { :username => @api_token }
+      { :username => self.api_token }
     end
-
   end
 end

data/lib/greenhouse_io/api/client.rb

@@ -0,0 +1,88 @@
+module GreenhouseIo
+  class Client
+    include HTTMultiParty
+    include GreenhouseIo::API
+
+    PERMITTED_OPTIONS = [:page, :per_page]
+
+    attr_accessor :api_token, :rate_limit, :rate_limit_remaining
+    base_uri 'https://harvest.greenhouse.io/v1'
+
+    def initialize(api_token = nil)
+      @api_token = api_token || GreenhouseIo.configuration.api_token
+    end
+
+    def offices(id = nil, options = {})
+      get_from_harvest_api "/offices#{path_id(id)}", options
+    end
+
+    def departments(id = nil, options = {})
+      get_from_harvest_api "/departments#{path_id(id)}", options
+    end
+
+    def candidates(id = nil, options = {})
+      get_from_harvest_api "/candidates#{path_id(id)}", options
+    end
+
+    def activity_feed(id, options = {})
+      get_from_harvest_api "/candidates/#{id}/activity_feed", options
+    end
+
+    def applications(id = nil, options = {})
+      get_from_harvest_api "/applications#{path_id(id)}", options
+    end
+
+    def scorecards(id, options = {})
+      get_from_harvest_api "/applications/#{id}/scorecards", options
+    end
+
+    def scheduled_interviews(id, options = {})
+      get_from_harvest_api "/applications/#{id}/scheduled_interviews", options
+    end
+
+    def jobs(id = nil, options = {})
+      get_from_harvest_api "/jobs#{path_id(id)}", options
+    end
+
+    def stages(id, options = {})
+      get_from_harvest_api "/jobs/#{id}/stages", options
+    end
+
+    def job_post(id, options = {})
+      get_from_harvest_api "/jobs/#{id}/job_post", options
+    end
+
+    def users(id = nil, options = {})
+      get_from_harvest_api "/users#{path_id(id)}", options
+    end
+
+    def sources(id = nil, options = {})
+      get_from_harvest_api "/sources#{path_id(id)}", options
+    end
+
+    private
+
+    def path_id(id = nil)
+      "/#{id}" unless id.nil?
+    end
+
+    def permitted_options(options)
+      options.select { |key, value| PERMITTED_OPTIONS.include? key }
+    end
+
+    def get_from_harvest_api(url, options = {})
+      response = get_response(url, query: permitted_options(options), basic_auth: basic_auth)
+      set_rate_limits(response.headers)
+      if response.code == 200
+        parse_json(response)
+      else
+        raise GreenhouseIo::Error.new(response.code)
+      end
+    end
+
+    def set_rate_limits(headers)
+      self.rate_limit = headers['x-ratelimit-limit'].to_i
+      self.rate_limit_remaining = headers['x-ratelimit-remaining'].to_i
+    end
+  end
+end

data/lib/greenhouse_io/api/job_board.rb

@@ -0,0 +1,66 @@
+module GreenhouseIo
+  class JobBoard
+    include HTTMultiParty
+    include GreenhouseIo::API
+    attr_accessor :api_token, :organization
+    base_uri 'https://api.greenhouse.io/v1'
+
+    def initialize(api_token = nil, default_options = {})
+      @api_token = api_token || GreenhouseIo.configuration.api_token
+      @organization = default_options.delete(:organization) || GreenhouseIo.configuration.organization
+    end
+
+    def offices(options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/offices")
+    end
+
+    def office(id, options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/office", query: { id: id })
+    end
+
+    def departments(options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/departments")
+    end
+
+    def department(id, options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/department", query: { id: id })
+    end
+
+    def jobs(options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/jobs", query: { content: options[:content] })
+    end
+
+    def job(id, options = {})
+      get_from_job_board_api("/boards/#{ query_organization(options) }/embed/job", query: { id: id, questions: options[:questions] })
+    end
+
+    def apply_to_job(job_form_hash)
+      post_to_job_board_api('/applications', { :body => job_form_hash, :basic_auth => basic_auth })
+    end
+
+    private
+
+    def query_organization(options_hash)
+      org = options_hash[:organization] || @organization
+      org.nil? ? (raise GreenhouseIo::Error.new("organization can't be blank")) : org
+    end
+
+    def get_from_job_board_api(url, options = {})
+      response = get_response(url, options)
+      if response.code == 200
+        parse_json(response)
+      else
+        raise GreenhouseIo::Error.new(response.code)
+      end
+    end
+
+    def post_to_job_board_api(url, options)
+      response = post_response(url, options)
+      if response.code == 200
+        response.include?("success") ? parse_json(response) : raise(GreenhouseIo::Error.new(response["reason"]))
+      else
+        raise GreenhouseIo::Error.new(response.code)
+      end
+    end
+  end
+end

data/lib/greenhouse_io/configuration.rb

@@ -0,0 +1,21 @@
+module GreenhouseIo
+  class Configuration
+    attr_accessor :symbolize_keys, :organization, :api_token
+
+    def initialize
+      @symbolize_keys = false
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield configuration
+  end
+end