bigcommerce 1.0.0.beta → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d098924abf4c82d2daa1a8dfdd09068a8960e771
-  data.tar.gz: d31b1ab3c0f9c52df72d16c06a00c72f615e21e0
+  metadata.gz: 699fc230ea09d9242c9cbfb7e1d2183891127627
+  data.tar.gz: 94e9e4eeb4a9b8cdf53ff2bd26f78612d8457d25
 SHA512:
-  metadata.gz: 4b520cad6ba40ea401e4a79e15ed7d0308dc8d87599382a6cb6b02972b4e30729351832cbbccedff8054fae635b6d769c0d9970528ed448d90e5a21de483602f
-  data.tar.gz: 81357d00e6c8cd9eec5a2d8123c68c33c36b7bb686369d82e80e30b8cbb6b9b378041f54cd21d64878e53508cedd613cb7d0aab8c4fb1183c1f04f6eb18e66ae
+  metadata.gz: 131581aaa53a9933c978f7649530128857e7a46e467c091b77effc27828ca895388bc78edfdd0cf5bb58bb14f8041a55417b90f52af98aab82480c3748563cc0
+  data.tar.gz: 88d65c0fa84ad4d4968e58b7780eaac14408d5ad123eafe1c1b158c04822ade1007cbf3c460c95235765efdb548baa0c34a4778b9a60283b8f45c4efa07479a1

data/README.md

@@ -1,54 +1,50 @@
-# Bigcommerce
+# BigCommerce API Ruby
 
-[![Gem Version](https://badge.fury.io/rb/bigcommerce.png)](https://rubygems.org/gems/bigcommerce)
-[![Build Status](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby.png?branch=master)](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby)
-[![Dependency Status](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby.png?travis)](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby)
-[![Code Climate](https://codeclimate.com/github/bigcommerce/bigcommerce-api-ruby.png)](https://codeclimate.com/github/bigcommerce/bigcommerce-api-ruby)
-[![Coverage Status](https://coveralls.io/repos/bigcommerce/bigcommerce-api-ruby/badge.png?branch=master)](https://coveralls.io/r/bigcommerce/bigcommerce-api-ruby?branch=master)
+[![Gem Version](https://badge.fury.io/rb/bigcommerce.svg)](https://rubygems.org/gems/bigcommerce)
+[![Build Status](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby.svg?branch=master)](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby)
+[![Dependency Status](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby.svg?travis)](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby)
 
-This is the official Bigcommerce API client to support our Rest API. You can find more information about becoming a Bigcommerce developer here: [developer.bigcommerce.com](http://developer.bigcommerce.com).
-
-#### ⚠️ A note about the current client: ⚠️
-This is a preview release of the 1.0.0 version of the Bigcommerce API Client. Please report issues if they come up.
-
-We have introduced a new major version of the API client and it is a complete rewrite (for the better). If you want to see the old version of the API client, please view it here: [Bigcommerce API client v0.x](https://github.com/bigcommerce/bigcommerce-api-ruby/tree/0.x). We recommend that developers upgrade to the latest client, but we will still support our developers who are unable to upgrade.
+This is the official BigCommerce API client to support our Stores API. You can find more information about becoming a BigCommerce developer here: [developer.bigcommerce.com](http://developer.bigcommerce.com).
 
 
 ## Installation
-Bigcommerce is available on Rubygems:
+BigCommerce is available on [RubyGems](https://rubygems.org/gems/bigcommerce).
 
 ```sh
-gem install bigcommerce --pre
+gem install bigcommerce
 ```
 
 You can also add it to your Gemfile.
 
 ```rb
-gem 'bigcommerce', '>= 1.0.0.beta'
+gem 'bigcommerce', '~> 1.0.0'
 ```
 
+## Requirements
+- Ruby 2.0.0 or newer. Please refer to the `.travis.yml` to see which versions we officially support.
+
 ## Getting Started
-In order to make requests to our API, you must register as a developer and have your credentials ready.
+In order to make requests to our API, you must register as a developer and have your credentials ready. 
 
-We currently have two different authentication schemes you can use depending on your use-case.
+Its also very important to note that for the OAuth authentication mechanism, the resources you have acccess to depend on the scopes which your application has been granted by the merchant. For more information about the Store API scopes, see: [OAuth Scopes](https://developer.bigcommerce.com/api/scopes).
 
-#### Public Apps
-Public apps can be submitted to Bigcommerce App Store, allowing other businesses to install it in their Bigcommerce stores.
+## Authentication
+We currently have two different authentication schemes you can use depending on your use case.
 
-[More Information](https://developer.bigcommerce.com/api/using-oauth-intro)
+### OAuth
+OAuth apps can be submitted to [BigCommerce App Store](https://www.bigcommerce.com/apps), allowing other merchants to install it in their BigCommerce store.
 
-#### Private Apps
-To develop a custom integration for one store, your app needs to use Basic Authentication.
+__[More Information](https://developer.bigcommerce.com/api/using-oauth-intro)__
 
-[More Information](https://developer.bigcommerce.com/api/legacy/basic-auth)
+### Basic Authentication (Legacy)
+To develop a custom integration for one store, your app needs to use Basic Authentication.
 
-## Usage
-For full examples on using the API client, please see the [examples folder](examples).
+__[More Information](https://developer.bigcommerce.com/api/legacy/basic-auth)__
 
 ## Configuration
-In order to authenticate the API client, you will need to configure the client like this:
+In order to authenticate the API client, you will need to configure the client like the following.
 
-#### Single Click (Public Apps):
+### OAuth App
 
 - ```client_id```: Obtained from the "My Apps" section on the [developer portal](http://developer.bigcommerce.com).
 - ```access_token```: Obtained after a token exchange in the auth callback.
@@ -56,26 +52,26 @@ In order to authenticate the API client, you will need to configure the client l
 
 ```rb
 Bigcommerce.configure do |config|
-  config.store_hash = 'store_hash'
-  config.client_id = 'client_id'
-  config.access_token = 'access_token'
+  config.store_hash = ENV['BC_STORE_HASH']
+  config.client_id = ENV['BC_CLIENT_ID']
+  config.access_token = ENV['BC_ACCESS_TOKEN']
 end
 ```
 
-#### Private Apps:
+### Basic Authentication (Legacy)
 
-To get all the private app credentials, simply visit your store admin page and navigate to the Settings > Legacy API Settings. Once there, you can create a new username to authenticate with.
+To get all the basic auth credentials, simply visit your store admin page and navigate to the `Advanced Settings > Legacy API Settings`. Once there, you can create a new legacy api account to authenticate with.
 
 ```rb
 Bigcommerce.configure do |config|
   config.auth = 'legacy'
-  config.url = 'https://api_path.com'
-  config.username = 'username'
-  config.api_key = 'api_key'
+  config.url = ENV['BC_API_ENDPOINT_LEGACY']
+  config.username = ENV['BC_USERNAME']
+  config.api_key = ENV['BC_API_KEY']
 end
 ```
 
-__SSL Configuration:__
+__SSL Configuration__
 
 If you are using your own self-signed certificate, you can pass SSL options to Faraday. This is not required, but may be useful in special edge cases.
 
@@ -96,5 +92,71 @@ For more information about configuring SSL with Faraday, please see the followin
 - [Faraday SSL example](https://gist.github.com/mislav/938183)
 - [Setting up SSL certificates](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates)
 
+
+## Usage
+For full examples on using the API client, please see the [examples folder](examples) and refer to the [developer documentation](https://developer.bigcommerce.com/api).
+
+Example:
+
+```rb
+# Configure the client to talk to a given store
+Bigcommerce.configure do |config|
+  config.store_hash = ENV['BC_STORE_HASH']
+  config.client_id = ENV['BC_CLIENT_ID']
+  config.access_token = ENV['BC_ACCESS_TOKEN']
+end
+
+# Make an API request for a given resource
+Bigcommerce::System.time
+=> #<Bigcommerce::System time=1466801314>
+```
+
+### Thread Safety
+
+The `Bigcommerce.configure` method is NOT thread safe. This mechanism is designed for applications or cli where thread safety is not a concern. If you need to guarantee thread safety, we support another mechanism to make threadsafe API requests.
+
+Rather then setting up a single `connection` for all API requests, you will want to construct a new connection for each thread. If you can make sure that each of these connections is stored in a thread safe manner, you can pass the `connection` as you query the resource.
+
+This connection is nothing more than a `Faraday::Connection` so if you want to write your own, or use your own adapers, you can feel free. Please refer to the [connection class](https://github.com/bigcommerce/bigcommerce-api-ruby/blob/master/lib/bigcommerce/connection.rb) for more details.
+
+##### OAuth
+
+```rb
+connection = Bigcommerce::Connection.build(
+  Bigcommerce::Config.new(
+    store_hash: ENV['BC_STORE_HASH'], 
+    client_id: ENV['BC_CLIENT_ID'], 
+    access_token: ENV['BC_ACCESS_TOKEN']
+  )
+)
+=> #<Faraday::Connection:0x007fbf95068978 ... >>
+
+Bigcommerce::System.time(connection: connection)
+=> #<Bigcommerce::System time=1466546702>
+
+Bigcommerce::System.raw_request(:get, 'time', connection: connection)
+=> #<Faraday::Response:0x007fd4a4063170 ... >>
+```
+
+##### Basic Auth
+
+```rb
+connection_legacy = Bigcommerce::Connection.build(
+  Bigcommerce::Config.new(
+    auth: 'legacy', 
+    url: ENV['BC_API_ENDPOINT_LEGACY'],
+    username: ENV['BC_USERNAME'],
+    api_key: ENV['BC_API_KEY']
+  )
+)
+=> #<Faraday::Connection:0x007fbf95068978 ... >>
+
+Bigcommerce::System.time(connection: connection_legacy)
+=> #<Bigcommerce::System time=1466546702>
+
+Bigcommerce::System.raw_request(:get, 'time', connection: connection_legacy)
+=> #<Faraday::Response:0x007fd4a4063170 ... >>
+```
+
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md)

data/bigcommerce.gemspec

@@ -4,25 +4,23 @@ require 'bigcommerce/version'
 
 Gem::Specification.new do |s|
   s.name = 'bigcommerce'
-  s.homepage = 'https://github.com/bigcommerce/bigcommerce-api-ruby'
-  s.authors = ['Patrick Edelman']
   s.version = Bigcommerce::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 2.0.0'
   s.license = 'MIT'
 
-  s.description = 'Bigcommerce API Ruby client library. Allows developers to \
-  easily communicate with the Bigcommerce API, for either CLI tools or public \
-  apps. More info: http://developer.bigcommerce.com'
-  s.summary = 'Ruby client library for the Bigcommerce v2 API'
+  s.authors = ['Patrick Edelman']
+  s.homepage = 'https://github.com/bigcommerce/bigcommerce-api-ruby'
+  s.summary = 'Ruby client library for the BigCommerce API'
+  s.description = s.summary
 
-  s.required_ruby_version = '>= 1.9.3'
   s.require_paths = ['lib']
-  s.files = `git ls-files`.split($ORS)
-  s.test_files = Dir['spec/**/*.rb']
+  s.files = Dir['README.md', 'lib/**/*', 'bigcommerce.gemspec']
 
-  s.add_development_dependency 'rake'
   s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rake'
 
-  s.add_dependency 'faraday'
-  s.add_dependency 'faraday_middleware'
-  s.add_dependency 'hashie'
+  s.add_dependency 'faraday', '~> 0.9'
+  s.add_dependency 'faraday_middleware', '~> 0.10.0'
+  s.add_dependency 'hashie', '~> 3.4'
 end

data/lib/bigcommerce.rb

@@ -1,6 +1,8 @@
 require 'hashie'
 require 'faraday_middleware'
 require 'bigcommerce/version'
+require 'bigcommerce/config'
+require 'bigcommerce/connection'
 require 'bigcommerce/middleware/auth'
 require 'bigcommerce/middleware/http_exception'
 require 'bigcommerce/resources/resource'
@@ -9,43 +11,12 @@ module Bigcommerce
   resources = File.join(File.dirname(__FILE__), 'bigcommerce', 'resources', '**', '*.rb')
   Dir.glob(resources, &method(:require))
 
-  DEFAULTS = {
-    base_url: 'https://api.bigcommerce.com'
-  }
-
-  HEADERS = {
-    'accept' => 'application/json',
-    'content-type' => 'application/json',
-    'user-agent' => 'bigcommerce-api-ruby'
-  }
-
   class << self
     attr_reader :api
-    attr_accessor :api_limit
 
     def configure
-      config = Hashie::Mash.new
-      yield(config)
-      ssl_options = config.ssl if config.auth == 'legacy'
-
-      @api = Faraday.new(url: build_url(config), ssl: ssl_options) do |conn|
-        conn.request :json
-        conn.headers = HEADERS
-        if config.auth == 'legacy'
-          conn.use Faraday::Request::BasicAuthentication, config.username, config.api_key
-        else
-          conn.use Bigcommerce::Middleware::Auth, config
-        end
-        conn.use Bigcommerce::Middleware::HttpException
-        conn.adapter Faraday.default_adapter
-      end
-    end
-
-    def build_url(config)
-      return config.url if config.auth == 'legacy'
-
-      base = ENV['BC_API_ENDPOINT'].nil? ? DEFAULTS[:base_url] : ENV['BC_API_ENDPOINT']
-      "#{base}/stores/#{config.store_hash}/v2"
+      @config = Bigcommerce::Config.new.tap { |h| yield(h) }
+      @api = Bigcommerce::Connection.build(@config)
     end
   end
 end

data/lib/bigcommerce/config.rb

@@ -0,0 +1,14 @@
+module Bigcommerce
+  class Config < Hashie::Mash
+    DEFAULTS = {
+      base_url: 'https://api.bigcommerce.com'
+    }.freeze
+
+    def api_url
+      return url if auth == 'legacy'
+
+      base = ENV['BC_API_ENDPOINT'].to_s.empty? ? DEFAULTS[:base_url] : ENV['BC_API_ENDPOINT']
+      "#{base}/stores/#{store_hash}/v2"
+    end
+  end
+end

data/lib/bigcommerce/connection.rb

@@ -0,0 +1,24 @@
+module Bigcommerce
+  module Connection
+    HEADERS = {
+      'accept' => 'application/json',
+      'content-type' => 'application/json',
+      'user-agent' => 'bigcommerce-api-ruby'
+    }.freeze
+
+    def self.build(config)
+      ssl_options = config.ssl if config.auth == 'legacy'
+      Faraday.new(url: config.api_url, ssl: ssl_options) do |conn|
+        conn.request :json
+        conn.headers = HEADERS
+        if config.auth == 'legacy'
+          conn.use Faraday::Request::BasicAuthentication, config.username, config.api_key
+        else
+          conn.use Bigcommerce::Middleware::Auth, config
+        end
+        conn.use Bigcommerce::Middleware::HttpException
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/bigcommerce/exception.rb

@@ -6,19 +6,19 @@ module Bigcommerce
     end
   end
 
-  class BadRequest             < HttpError; end
-  class Unauthorized           < HttpError; end
-  class Forbidden              < HttpError; end
-  class NotFound               < HttpError; end
-  class MethodNotAllowed       < HttpError; end
-  class NotAccepted            < HttpError; end
-  class TimeOut                < HttpError; end
-  class ResourceConflict       < HttpError; end
-  class TooManyRequests        < HttpError; end
-  class InternalServerError    < HttpError; end
-  class BadGateway             < HttpError; end
-  class ServiceUnavailable     < HttpError; end
-  class GatewayTimeout         < HttpError; end
+  class BadRequest < HttpError; end
+  class Unauthorized < HttpError; end
+  class Forbidden < HttpError; end
+  class NotFound < HttpError; end
+  class MethodNotAllowed < HttpError; end
+  class NotAccepted < HttpError; end
+  class TimeOut < HttpError; end
+  class ResourceConflict < HttpError; end
+  class TooManyRequests < HttpError; end
+  class InternalServerError < HttpError; end
+  class BadGateway < HttpError; end
+  class ServiceUnavailable < HttpError; end
+  class GatewayTimeout < HttpError; end
   class BandwidthLimitExceeded < HttpError; end
 
   module HttpErrors
@@ -37,15 +37,22 @@ module Bigcommerce
       503 => Bigcommerce::ServiceUnavailable,
       504 => Bigcommerce::GatewayTimeout,
       509 => Bigcommerce::BandwidthLimitExceeded
-    }
+    }.freeze
 
     def throw_http_exception!(code, env)
       return unless ERRORS.keys.include? code
-      error_hash = env.body.empty? ? {} : JSON.parse(env.body, symbolize_names: true)
-      unless env[:response_headers]['X-Retry-After'].nil?
-        error_hash[:retry_after] = env[:response_headers]['X-Retry-After'].to_i
+      response_headers = {}
+      unless env.body.empty?
+        response_headers = begin
+          JSON.parse(env.body, symbolize_names: true)
+        rescue
+          {}
+        end
       end
-      fail ERRORS[code].new(error_hash), env.body
+      unless env[:response_headers] && env[:response_headers]['X-Retry-After'].nil?
+        response_headers[:retry_after] = env[:response_headers]['X-Retry-After'].to_i
+      end
+      raise ERRORS[code].new(response_headers), env.body
     end
   end
 end

data/lib/bigcommerce/request.rb

@@ -43,30 +43,29 @@ module Bigcommerce
     end
 
     module ClassMethods
-      def get(path, params = nil)
+      def get(path, params = {})
         response = raw_request(:get, path, params)
         build_response_object response
       end
 
-      def delete(path)
-        response = raw_request(:delete, path)
+      def delete(path, params = {})
+        response = raw_request(:delete, path, params)
         response.body
       end
 
-      def post(path, params)
+      def post(path, params = {})
         response = raw_request(:post, path, params)
         build_response_object response
       end
 
-      def put(path, params)
+      def put(path, params = {})
         response = raw_request(:put, path, params)
         build_response_object response
       end
 
-      def raw_request(method, path, params = nil)
-        response = Bigcommerce.api.send(method, path.to_s, params)
-        Bigcommerce.api_limit = response.headers['X-BC-ApiLimit-Remaining']
-        response
+      def raw_request(method, path, params = {})
+        client = params.delete(:connection) || Bigcommerce.api
+        client.send(method, path.to_s, params)
       end
 
       private

data/lib/bigcommerce/resource_actions.rb

@@ -24,27 +24,27 @@ module Bigcommerce
         get path.build, params
       end
 
-      def find(resource_id)
-        fail ArgumentError if resource_id.nil?
-        get path.build(resource_id)
+      def find(resource_id, params = {})
+        raise ArgumentError if resource_id.nil?
+        get path.build(resource_id), params
       end
 
-      def create(params)
+      def create(params = {})
         post path.build, params
       end
 
-      def update(resource_id, params)
-        fail ArgumentError if resource_id.nil?
+      def update(resource_id, params = {})
+        raise ArgumentError if resource_id.nil?
         put path.build(resource_id), params
       end
 
-      def destroy(resource_id)
-        fail ArgumentError if resource_id.nil?
-        delete path.build(resource_id)
+      def destroy(resource_id, params = {})
+        raise ArgumentError if resource_id.nil?
+        delete path.build(resource_id), params
       end
 
-      def destroy_all
-        delete path.build
+      def destroy_all(params = {})
+        delete path.build, params
       end
     end
   end