gibbon 3.5.0 → 4.0.1

data/lib/gibbon/request.rb

@@ -1,11 +1,42 @@
 module Gibbon
+  # Builds and issues requests against MailChimp's Marketing API.
+  #
+  # `Request` defines no methods for MailChimp's resources. An unknown method
+  # appends a segment to an internal path and returns `self`, so
+  # `gibbon.lists(list_id).members` builds `lists/<list_id>/members`. A CRUD
+  # verb ({#create}, {#retrieve}, {#update}, {#upsert}, {#delete}) then issues
+  # the request and resets the path. Because of that reset, an instance is safe
+  # to reuse only after a verb has run.
+  #
+  # @example Fetching lists
+  #   gibbon = Gibbon::Request.new(api_key: "your_api_key-us1")
+  #   gibbon.lists.retrieve.body["lists"]
+  #
+  # @see https://mailchimp.com/developer/marketing/api/ MailChimp's resource documentation
   class Request
+    # Per-instance configuration. Each falls back to the matching class level
+    # setting, then to an environment variable or built-in default; see
+    # {#initialize} for the resolution order.
     attr_accessor :api_key, :api_endpoint, :timeout, :open_timeout, :proxy, :faraday_adapter, :symbolize_keys, :debug, :logger
 
+    # Default read timeout, in seconds.
     DEFAULT_TIMEOUT = 60
+    # Default connection open timeout, in seconds.
     DEFAULT_OPEN_TIMEOUT = 60
 
-    def initialize(api_key: nil, api_endpoint: nil, timeout: nil, open_timeout: nil, proxy: nil, faraday_adapter: nil, symbolize_keys: false, debug: false, logger: nil)
+    # @param api_key [String, nil] API key or OAuth access token. Falls back to
+    #   `Gibbon::Request.api_key`, then `ENV["MAILCHIMP_API_KEY"]`.
+    # @param api_endpoint [String, nil] Base URL, e.g. `"https://us1.api.mailchimp.com"`.
+    #   Required when the key carries no data center suffix, as OAuth access
+    #   tokens do not; otherwise it is derived from the key.
+    # @param timeout [Integer, nil] Read timeout in seconds. Defaults to {DEFAULT_TIMEOUT}.
+    # @param open_timeout [Integer, nil] Open timeout in seconds. Defaults to {DEFAULT_OPEN_TIMEOUT}.
+    # @param proxy [String, nil] Proxy URL. Falls back to `ENV["MAILCHIMP_PROXY"]`.
+    # @param faraday_adapter [Symbol, nil] Faraday adapter. Defaults to `Faraday.default_adapter`.
+    # @param symbolize_keys [Boolean] Whether parsed response bodies use symbol keys.
+    # @param debug [Boolean] Whether to log requests and responses.
+    # @param logger [Logger, nil] Logger used when `debug` is true. Defaults to `Logger.new(STDOUT)`.
+    def initialize(api_key: nil, api_endpoint: nil, timeout: nil, open_timeout: nil, proxy: nil, faraday_adapter: nil, symbolize_keys: nil, debug: nil, logger: nil)
       @path_parts = []
       @api_key = api_key || self.class.api_key || ENV['MAILCHIMP_API_KEY']
       @api_key = @api_key.strip if @api_key
@@ -14,11 +45,15 @@ module Gibbon
       @open_timeout = open_timeout || self.class.open_timeout || DEFAULT_OPEN_TIMEOUT
       @proxy = proxy || self.class.proxy || ENV['MAILCHIMP_PROXY']
       @faraday_adapter = faraday_adapter || self.class.faraday_adapter || Faraday.default_adapter
-      @symbolize_keys = symbolize_keys || self.class.symbolize_keys || false
-      @debug = debug || self.class.debug || false
+      @symbolize_keys = symbolize_keys.nil? ? (self.class.symbolize_keys || false) : symbolize_keys
+      @debug = debug.nil? ? (self.class.debug || false) : debug
       @logger = logger || self.class.logger || ::Logger.new(STDOUT)
     end
 
+    # Appends the method name to the request path, along with any arguments as
+    # further segments, and returns `self` so calls can be chained.
+    #
+    # @return [Request] self
     def method_missing(method, *args)
       # To support underscores, we replace them with hyphens when calling the API
       @path_parts << method.to_s.gsub("_", "-").downcase
@@ -27,10 +62,19 @@ module Gibbon
       self
     end
 
+    # Every method name is a potential path segment, so this always returns true.
+    #
+    # @return [true]
     def respond_to_missing?(method_name, include_private = false)
       true
     end
 
+    # Appends `send` as a path segment when called with no arguments, so that
+    # `gibbon.campaigns(id).actions.send.create` reaches
+    # `campaigns/<id>/actions/send`. Called with arguments, this behaves like
+    # `Object#send` and invokes the named method.
+    #
+    # @return [Request, Object] self, or the return value of the invoked method
     def send(*args)
       if args.length == 0
         method_missing(:send, args)
@@ -39,38 +83,75 @@ module Gibbon
       end
     end
 
+    # @return [String] the path accumulated so far, e.g. `"lists/abc123/members"`
     def path
       @path_parts.join('/')
     end
 
+    # Issues a `POST` to the accumulated path, then resets it.
+    #
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @param body [Hash, nil] request body, serialized to JSON
+    # @return [Response, nil] the response, or nil when MailChimp returns an empty body
+    # @raise [GibbonError] if no usable API key is configured
+    # @raise [MailChimpError] if the request fails or the response cannot be parsed
     def create(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).post(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Issues a `PATCH` to the accumulated path, then resets it.
+    #
+    # @param (see #create)
+    # @return (see #create)
+    # @raise (see #create)
     def update(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).patch(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Issues a `PUT` to the accumulated path, then resets it. Updates the record
+    # if it exists and inserts it otherwise, where MailChimp supports it.
+    #
+    # @param (see #create)
+    # @return (see #create)
+    # @raise (see #create)
     def upsert(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).put(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Alias for {#retrieve}.
+    #
+    # @param (see #retrieve)
+    # @return (see #retrieve)
+    # @raise (see #retrieve)
     def get(params: nil, headers: nil)
       retrieve(params: params, headers: headers)
     end
 
+    # Issues a `GET` to the accumulated path, then resets it.
+    #
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @return [Response, nil] the response, or nil when MailChimp returns an empty body
+    # @raise [GibbonError] if no usable API key is configured
+    # @raise [MailChimpError] if the request fails or the response cannot be parsed
     def retrieve(params: nil, headers: nil)
       APIRequest.new(builder: self).get(params: params, headers: headers)
     ensure
       reset
     end
 
+    # Issues a `DELETE` to the accumulated path, then resets it.
+    #
+    # @param (see #retrieve)
+    # @return (see #retrieve)
+    # @raise (see #retrieve)
     def delete(params: nil, headers: nil)
       APIRequest.new(builder: self).delete(params: params, headers: headers)
     ensure
@@ -84,12 +165,22 @@ module Gibbon
     end
 
     class << self
+      # Class level defaults applied to every new instance. Setting these is a
+      # convenient way to configure Gibbon once, e.g. from a Rails initializer.
       attr_accessor :api_key, :timeout, :open_timeout, :api_endpoint, :proxy, :faraday_adapter, :symbolize_keys, :debug, :logger
 
+      # Starts a call chain on a new instance built from the class level
+      # configuration, so `Gibbon::Request.lists.retrieve` works once
+      # {api_key} has been set.
+      #
+      # @return [Request] a new instance carrying the first path segment
       def method_missing(sym, *args, &block)
         new(api_key: self.api_key, api_endpoint: self.api_endpoint, timeout: self.timeout, open_timeout: self.open_timeout, faraday_adapter: self.faraday_adapter, symbolize_keys: self.symbolize_keys, debug: self.debug, proxy: self.proxy, logger: self.logger).send(sym, *args, &block)
       end
 
+      # Every method name is a potential path segment, so this always returns true.
+      #
+      # @return [true]
       def respond_to_missing?(method_name, include_private = false)
         true
       end

data/lib/gibbon/response.rb

@@ -1,7 +1,20 @@
 module Gibbon
+  # A parsed response from MailChimp, returned by every CRUD verb on {Request}.
+  #
+  # @example
+  #   response = gibbon.lists.retrieve
+  #   response.body["lists"]
+  #   response.headers["content-type"]
   class Response
-    attr_accessor :body, :headers
-    
+    # @return [Hash, Array] the parsed JSON response body. Keys are symbols when
+    #   the request was built with `symbolize_keys: true`, strings otherwise.
+    attr_accessor :body
+
+    # @return [Hash] the response headers, keyed by lower case string.
+    attr_accessor :headers
+
+    # @param body [Hash, Array] the parsed response body
+    # @param headers [Hash] the response headers
     def initialize(body: {}, headers: {})
       @body = body
       @headers = headers

data/lib/gibbon/version.rb

@@ -1,3 +1,4 @@
 module Gibbon
-  VERSION = "3.5.0"
+  # The released version of the gem.
+  VERSION = "4.0.1"
 end

data/lib/gibbon.rb

@@ -10,5 +10,6 @@ require 'gibbon/request'
 require 'gibbon/api_request'
 require 'gibbon/response'
 
+# A Ruby wrapper for MailChimp's Marketing API. See {Gibbon::Request}.
 module Gibbon
 end

data/spec/gibbon/api_request_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'webmock/rspec'
+require 'stringio'
 
 describe Gibbon::APIRequest do
   let(:api_key) { "1234-us1" }
@@ -66,4 +67,176 @@ describe Gibbon::APIRequest do
 
     include_examples 'client error handling'
   end
+
+  context 'Faraday::ServerError' do
+    let(:error_class) { Faraday::ServerError }
+
+    include_examples 'client error handling'
+  end
+
+  context "error responses over HTTP" do
+    it "raises a MailChimpError with details parsed from a 4xx JSON response" do
+      error_body = '{"title": "Invalid Resource", "detail": "The resource submitted could not be validated.", "status": 422}'
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 422, body: error_body, headers: { 'Content-Type' => 'application/json' })
+
+      begin
+        @gibbon.lists.retrieve
+        fail "expected a Gibbon::MailChimpError"
+      rescue Gibbon::MailChimpError => e
+        expect(e.status_code).to eq 422
+        expect(e.title).to eq "Invalid Resource"
+        expect(e.detail).to eq "The resource submitted could not be validated."
+        expect(e.raw_body).to eq error_body
+        expect(e.body).to eq MultiJson.load(error_body)
+      end
+    end
+
+    it "raises a MailChimpError on a 5xx response" do
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 503, body: '{"title": "Service Unavailable"}')
+
+      begin
+        @gibbon.lists.retrieve
+        fail "expected a Gibbon::MailChimpError"
+      rescue Gibbon::MailChimpError => e
+        expect(e.status_code).to eq 503
+        expect(e.title).to eq "Service Unavailable"
+      end
+    end
+  end
+
+  context "response parsing" do
+    it "returns a Gibbon::Response with the parsed body and headers" do
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 200, body: '{"lists": [{"id": "abc123"}]}', headers: { 'Content-Type' => 'application/json' })
+
+      response = @gibbon.lists.retrieve
+      expect(response).to be_a Gibbon::Response
+      expect(response.body).to eq({ "lists" => [{ "id" => "abc123" }] })
+      expect(response.headers["content-type"]).to eq "application/json"
+    end
+
+    it "symbolizes response keys when symbolize_keys is true" do
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 200, body: '{"lists": [{"id": "abc123"}]}')
+
+      response = Gibbon::Request.new(api_key: api_key, symbolize_keys: true).lists.retrieve
+      expect(response.body).to eq({ lists: [{ id: "abc123" }] })
+    end
+
+    it "returns nil for an empty response body" do
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 200, body: "")
+
+      expect(@gibbon.lists.retrieve).to be_nil
+    end
+
+    it "raises a MailChimpError with details intact for an unparseable success response" do
+      stub_request(:get, "#{@api_root}/lists")
+        .with(basic_auth: @basic_auth_credentials)
+        .to_return(status: 200, body: "not json")
+
+      begin
+        @gibbon.lists.retrieve
+        fail "expected a Gibbon::MailChimpError"
+      rescue Gibbon::MailChimpError => e
+        expect(e.title).to eq "UNPARSEABLE_RESPONSE"
+        expect(e.status_code).to eq 500
+      end
+    end
+  end
+
+  context "instance overrides of class defaults" do
+    before do
+      allow(Gibbon::Request).to receive(:symbolize_keys).and_return(true)
+      allow(Gibbon::Request).to receive(:debug).and_return(true)
+    end
+
+    let(:log_output) { StringIO.new }
+    let(:gibbon) do
+      Gibbon::Request.new(api_key: api_key, symbolize_keys: false, debug: false, logger: Logger.new(log_output))
+    end
+
+    it "returns string keys, including nested keys, when symbolization is disabled" do
+      stub_request(:get, "#{@api_root}/lists")
+        .to_return(body: '{"lists": [{"id": "abc123"}]}')
+
+      expect(gibbon.lists.retrieve.body).to eq({ "lists" => [{ "id" => "abc123" }] })
+      expect(Gibbon::Request.symbolize_keys).to be true
+    end
+
+    it "preserves error details with string keys when symbolization is disabled" do
+      error_body = '{"title": "Invalid Resource", "detail": "Invalid email address"}'
+      stub_request(:get, "#{@api_root}/lists").to_return(status: 422, body: error_body)
+
+      expect { gibbon.lists.retrieve }.to raise_error(Gibbon::MailChimpError) { |error|
+        expect(error.status_code).to eq 422
+        expect(error.title).to eq "Invalid Resource"
+        expect(error.detail).to eq "Invalid email address"
+        expect(error.body).to eq({ "title" => "Invalid Resource", "detail" => "Invalid email address" })
+        expect(error.raw_body).to eq error_body
+      }
+    end
+
+    it "does not log requests or responses when debug is disabled" do
+      stub_request(:get, "#{@api_root}/lists")
+        .to_return(body: '{"email_address": "private@example.com"}')
+
+      gibbon.lists.retrieve
+
+      expect(log_output.string).to be_empty
+      expect(Gibbon::Request.debug).to be true
+    end
+  end
+
+  context "configure_request" do
+    it "sets params, headers, body, and timeouts on the request" do
+      gibbon = Gibbon::Request.new(api_key: api_key, timeout: 45, open_timeout: 15)
+      api_request = Gibbon::APIRequest.new(builder: gibbon.lists)
+      request = Struct.new(:params, :headers, :body, :options).new({}, {}, nil, Faraday::RequestOptions.new)
+
+      api_request.send(:configure_request, request: request, params: { "count" => "10" }, headers: { "X-Custom" => "value" }, body: '{"a":1}')
+
+      expect(request.params).to eq({ "count" => "10" })
+      expect(request.headers).to eq({ "Content-Type" => "application/json", "X-Custom" => "value" })
+      expect(request.body).to eq '{"a":1}'
+      expect(request.options.timeout).to eq 45
+      expect(request.options.open_timeout).to eq 15
+    end
+  end
+
+  context "rest_client configuration" do
+    it "includes the logger middleware when debug is enabled" do
+      gibbon = Gibbon::Request.new(api_key: api_key, debug: true)
+      client = Gibbon::APIRequest.new(builder: gibbon.lists).send(:rest_client)
+      expect(client.builder.handlers).to include(Faraday::Response::Logger)
+    end
+
+    it "omits the logger middleware by default" do
+      client = Gibbon::APIRequest.new(builder: @gibbon.lists).send(:rest_client)
+      expect(client.builder.handlers).not_to include(Faraday::Response::Logger)
+    end
+
+    it "configures the proxy" do
+      gibbon = Gibbon::Request.new(api_key: api_key, proxy: "http://proxy.example.com:8080")
+      client = Gibbon::APIRequest.new(builder: gibbon.lists).send(:rest_client)
+      expect(client.proxy.host).to eq "proxy.example.com"
+      expect(client.proxy.port).to eq 8080
+    end
+  end
+
+  context "rest_client ssl configuration" do
+    it "requires TLS 1.2 as a minimum without capping the TLS version" do
+      api_request = Gibbon::APIRequest.new(builder: @gibbon.lists)
+      client = api_request.send(:rest_client)
+      expect(client.ssl.min_version).to eq :TLS1_2
+      expect(client.ssl.max_version).to be_nil
+    end
+  end
 end

data/spec/gibbon/gibbon_helpers_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Gibbon::Helpers do
+  let(:helper) { Class.new { include Gibbon::Helpers }.new }
+
+  describe "#get_data_center_from_api_key" do
+    it "returns an empty string for a nil api key" do
+      expect(helper.get_data_center_from_api_key(nil)).to eq("")
+    end
+
+    it "returns an empty string for an api key without a data center" do
+      expect(helper.get_data_center_from_api_key("1234")).to eq("")
+    end
+
+    it "returns the data center with a trailing dot" do
+      expect(helper.get_data_center_from_api_key("1234-us1")).to eq("us1.")
+    end
+
+    it "uses the last segment of a key containing multiple hyphens" do
+      expect(helper.get_data_center_from_api_key("12-34-us10")).to eq("us10.")
+    end
+
+    it "strips non-alphanumeric characters to prevent domain injection" do
+      expect(helper.get_data_center_from_api_key("1234-attacker.net/path?")).to eq("attackernetpath.")
+    end
+  end
+end

data/spec/gibbon/gibbon_spec.rb

@@ -219,10 +219,26 @@ describe Gibbon do
       expect(Gibbon::Request.new.symbolize_keys).to eq(Gibbon::Request.symbolize_keys)
     end
 
+    it "allows instance symbolize_keys false to override the class setting" do
+      expect(Gibbon::Request.new(symbolize_keys: false).symbolize_keys).to be false
+    end
+
+    it "inherits the class symbolize_keys setting when explicitly passed nil" do
+      expect(Gibbon::Request.new(symbolize_keys: nil).symbolize_keys).to be true
+    end
+
     it "set debug on new instances" do
       expect(Gibbon::Request.new.debug).to eq(Gibbon::Request.debug)
     end
 
+    it "allows instance debug false to override the class setting" do
+      expect(Gibbon::Request.new(debug: false).debug).to be false
+    end
+
+    it "inherits the class debug setting when explicitly passed nil" do
+      expect(Gibbon::Request.new(debug: nil).debug).to be true
+    end
+
     it "set faraday_adapter on new instances" do
       expect(Gibbon::Request.new.faraday_adapter).to eq(Gibbon::Request.faraday_adapter)
     end

data/spec/gibbon/mailchimp_error_spec.rb

@@ -46,4 +46,22 @@ describe Gibbon::MailChimpError do
   it 'sets the status_code attribute' do
     expect(@gibbon.status_code).to eq(params[:status_code])
   end
+
+  context "without params" do
+    before do
+      @gibbon = Gibbon::MailChimpError.new(message)
+    end
+
+    it "leaves the attributes nil" do
+      expect(@gibbon.title).to be_nil
+      expect(@gibbon.detail).to be_nil
+      expect(@gibbon.body).to be_nil
+      expect(@gibbon.raw_body).to be_nil
+      expect(@gibbon.status_code).to be_nil
+    end
+
+    it "still includes the attributes in the message" do
+      expect(@gibbon.message).to eq "Foo @title=nil, @detail=nil, @body=nil, @raw_body=nil, @status_code=nil"
+    end
+  end
 end

data/spec/gibbon/request_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+require 'webmock/rspec'
+
+describe Gibbon::Request do
+  let(:api_key) { "1234-us1" }
+  let(:api_root) { "https://us1.api.mailchimp.com/3.0" }
+  let(:basic_auth_credentials) { ['apikey', api_key] }
+
+  before do
+    @gibbon = Gibbon::Request.new(api_key: api_key)
+  end
+
+  describe "path building" do
+    it "builds a path from chained calls" do
+      @gibbon.lists("list123").members
+      expect(@gibbon.path).to eq("lists/list123/members")
+    end
+
+    it "replaces underscores with hyphens" do
+      @gibbon.lists("list123").interest_categories
+      expect(@gibbon.path).to eq("lists/list123/interest-categories")
+    end
+
+    it "downcases path parts" do
+      @gibbon.LISTS
+      expect(@gibbon.path).to eq("lists")
+    end
+
+    it "responds to any method" do
+      expect(@gibbon.respond_to?(:anything_at_all)).to be true
+    end
+
+    it "appends 'send' to the path when called without arguments" do
+      @gibbon.campaigns("abc").actions.send
+      expect(@gibbon.path).to eq("campaigns/abc/actions/send")
+    end
+
+    it "dispatches send with arguments as a regular method call" do
+      expect(@gibbon.send(:api_key)).to eq(api_key)
+    end
+
+    it "resets the path after a request" do
+      stub_request(:get, "#{api_root}/lists").with(basic_auth: basic_auth_credentials).to_return(status: 200)
+      @gibbon.lists.retrieve
+      expect(@gibbon.path).to eq("")
+    end
+
+    it "resets the path when a request raises" do
+      stub_request(:get, "#{api_root}/lists").with(basic_auth: basic_auth_credentials).to_return(status: 500, body: "{}")
+      expect { @gibbon.lists.retrieve }.to raise_error(Gibbon::MailChimpError)
+      expect(@gibbon.path).to eq("")
+    end
+  end
+
+  describe "HTTP verb mapping" do
+    let(:body) { { name: "Foo" } }
+
+    it "maps create to POST" do
+      stub = stub_request(:post, "#{api_root}/lists")
+        .with(body: MultiJson.dump(body), basic_auth: basic_auth_credentials, headers: { 'Content-Type' => 'application/json' })
+        .to_return(status: 200)
+      @gibbon.lists.create(body: body)
+      expect(stub).to have_been_requested
+    end
+
+    it "maps update to PATCH" do
+      stub = stub_request(:patch, "#{api_root}/lists/list123")
+        .with(body: MultiJson.dump(body), basic_auth: basic_auth_credentials, headers: { 'Content-Type' => 'application/json' })
+        .to_return(status: 200)
+      @gibbon.lists("list123").update(body: body)
+      expect(stub).to have_been_requested
+    end
+
+    it "maps upsert to PUT" do
+      stub = stub_request(:put, "#{api_root}/lists/list123")
+        .with(body: MultiJson.dump(body), basic_auth: basic_auth_credentials, headers: { 'Content-Type' => 'application/json' })
+        .to_return(status: 200)
+      @gibbon.lists("list123").upsert(body: body)
+      expect(stub).to have_been_requested
+    end
+
+    it "maps retrieve to GET" do
+      stub = stub_request(:get, "#{api_root}/lists").with(basic_auth: basic_auth_credentials).to_return(status: 200)
+      @gibbon.lists.retrieve
+      expect(stub).to have_been_requested
+    end
+
+    it "maps get to GET" do
+      stub = stub_request(:get, "#{api_root}/lists").with(basic_auth: basic_auth_credentials).to_return(status: 200)
+      @gibbon.lists.get
+      expect(stub).to have_been_requested
+    end
+
+    it "maps delete to DELETE" do
+      stub = stub_request(:delete, "#{api_root}/lists/list123").with(basic_auth: basic_auth_credentials).to_return(status: 204)
+      @gibbon.lists("list123").delete
+      expect(stub).to have_been_requested
+    end
+  end
+
+  describe "request options" do
+    it "passes query params" do
+      stub = stub_request(:get, "#{api_root}/lists")
+        .with(query: { "count" => "10", "offset" => "20" }, basic_auth: basic_auth_credentials)
+        .to_return(status: 200)
+      @gibbon.lists.retrieve(params: { "count" => "10", "offset" => "20" })
+      expect(stub).to have_been_requested
+    end
+
+    it "passes custom headers" do
+      stub = stub_request(:get, "#{api_root}/lists")
+        .with(headers: { 'X-Custom' => 'custom-value' }, basic_auth: basic_auth_credentials)
+        .to_return(status: 200)
+      @gibbon.lists.retrieve(headers: { 'X-Custom' => 'custom-value' })
+      expect(stub).to have_been_requested
+    end
+  end
+
+  describe "api key handling" do
+    it "strips whitespace from the api key" do
+      gibbon = Gibbon::Request.new(api_key: "  #{api_key}  ")
+      expect(gibbon.api_key).to eq(api_key)
+    end
+  end
+
+  describe "class-level requests" do
+    before do
+      Gibbon::Request.api_key = api_key
+    end
+
+    after do
+      Gibbon::Request.api_key = nil
+    end
+
+    it "makes requests directly on the class" do
+      stub = stub_request(:get, "#{api_root}/lists").with(basic_auth: basic_auth_credentials).to_return(status: 200)
+      Gibbon::Request.lists.retrieve
+      expect(stub).to have_been_requested
+    end
+  end
+end

data/spec/gibbon/response_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Gibbon::Response do
+  it "defaults body and headers to empty hashes" do
+    response = Gibbon::Response.new
+    expect(response.body).to eq({})
+    expect(response.headers).to eq({})
+  end
+
+  it "exposes the body and headers it is given" do
+    body = { "id" => "abc" }
+    headers = { "content-type" => "application/json" }
+    response = Gibbon::Response.new(body: body, headers: headers)
+    expect(response.body).to eq(body)
+    expect(response.headers).to eq(headers)
+  end
+end