module Etsy

Etsy: A friendly Ruby interface to the Etsy API

Quick Start

Getting started is easy. First, you will need a valid API key from the Etsy developer site (developer.etsy.com/).

To start using the API, require the etsy gem and set it up to use your API key:

require 'rubygems'
require 'etsy'

Etsy.api_key = 'itsasecret'

Now you can make API calls that originate from an Etsy user:

# Find a user by username
user = Etsy.user('littletjane')

# Grab that user's shop information
user.shop
user.shop.title

# ... and the listings in the shop
listing = user.shop.listings.first
listing.title
listing.description

To see what else is available for a user, check out the full documentation for the Etsy::User class. Information about making authenticated calls is available in the README.

Constants

PRODUCTION_HOST
SANDBOX_HOST
VERSION

Attributes

callback_url[W]
permission_scopes[W]

Public Class Methods

access_token(request_token, request_secret, verifier) click to toggle source

Generate an access token from the request token, secret, and verifier. The verifier can either be passed manually or from the params in the callback URL.

# File lib/etsy.rb, line 184
def self.access_token(request_token, request_secret, verifier)
  @access_token = begin
    client = Etsy::SecureClient.new({
      :request_token  => request_token,
      :request_secret => request_secret,
      :verifier       => verifier
    })
    client.client
  end
end
api_key() click to toggle source

Make Etsy.api_key and Etsy.api_secret global but also local to threads

# File lib/etsy.rb, line 80
def self.api_key
  Thread.current[:etsy_api_key] || @api_key
end
api_key=(key) click to toggle source
# File lib/etsy.rb, line 84
def self.api_key=(key)
  @api_key ||= key
  Thread.current[:etsy_api_key] = key
end
api_secret() click to toggle source
# File lib/etsy.rb, line 89
def self.api_secret
  Thread.current[:etsy_api_secret] || @api_secret
end
api_secret=(secret) click to toggle source
# File lib/etsy.rb, line 93
def self.api_secret=(secret)
  @api_secret ||= secret
  Thread.current[:etsy_api_secret] = secret
end
callback_url() click to toggle source

The configured callback URL or 'oob' if no callback URL is configured. This controls whether or not we need to pass the OAuth verifier by hand.

# File lib/etsy.rb, line 151
def self.callback_url
  @callback_url || 'oob'
end
credentials() click to toggle source
# File lib/etsy.rb, line 209
def self.credentials
  @credentials || {}
end
environment() click to toggle source

The currently configured environment.

# File lib/etsy.rb, line 134
def self.environment
  @environment || :production
end
environment=(environment) click to toggle source

Set the environment, accepts either :sandbox or :production. Defaults to :sandbox and will raise an exception when set to an unrecognized environment.

# File lib/etsy.rb, line 104
def self.environment=(environment)
  unless [:sandbox, :production].include?(environment)
    raise(ArgumentError, "environment must be set to either :sandbox or :production")
  end
  @environment = environment
  @host = (environment == :sandbox) ? SANDBOX_HOST : PRODUCTION_HOST
end
myself(token, secret, options = {}) click to toggle source

Convenience method for accessing the authenticated user's own user information. Requires authentication.

# File lib/etsy.rb, line 170
def self.myself(token, secret, options = {})
  User.myself(token, secret, options)
end
permission_scopes() click to toggle source

OAuth permission scopes. Defines which private fields we can have access to.

# File lib/etsy.rb, line 157
def self.permission_scopes
  @permission_scopes || []
end
protocol() click to toggle source
# File lib/etsy.rb, line 128
def self.protocol
  @protocol || "https"
end
protocol=(protocol) click to toggle source
# File lib/etsy.rb, line 112
def self.protocol=(protocol)
  unless ["http", "https"].include?(protocol.to_s)
    raise(ArgumentError, "protocol must be set to either 'http' or 'https'")
  end
  @protocol = protocol.to_s
end
request_token() click to toggle source

Generate a request token for authorization.

# File lib/etsy.rb, line 176
def self.request_token
  clear_for_new_authorization
  verification_request.request_token
end
silent_errors() click to toggle source

The default will change to false for a 1.0 release (breaking changes)

# File lib/etsy.rb, line 140
def self.silent_errors
  @silent_errors.nil? ? true : @silent_errors
end
silent_errors=(bool) click to toggle source

Allow throwing API errors

# File lib/etsy.rb, line 121
def self.silent_errors=(bool)
  unless [TrueClass, FalseClass].include?(bool.class)
    raise(ArgumentError, "Silent errors must be set to either true or false'")
  end
  @silent_errors = bool
end
single_user(access_token, access_secret) click to toggle source
# File lib/etsy.rb, line 201
def self.single_user(access_token, access_secret)
  @credentials = {
    :access_token => access_token,
    :access_secret => access_secret
  }
  nil
end
user(username) click to toggle source

Find a user by username. See Etsy::User for more information.

# File lib/etsy.rb, line 163
def self.user(username)
  User.find(username)
end
verification_url() click to toggle source

Generate the URL to begin the verification process for a user.

# File lib/etsy.rb, line 197
def self.verification_url
  verification_request.url
end

Private Class Methods

clear_for_new_authorization() click to toggle source
# File lib/etsy.rb, line 219
def self.clear_for_new_authorization
  @verification_request = nil
end
deprecate(message) click to toggle source
# File lib/etsy.rb, line 223
def self.deprecate(message)
  puts "DEPRECATED: #{message}."
end
verification_request() click to toggle source
# File lib/etsy.rb, line 215
def self.verification_request
  @verification_request ||= VerificationRequest.new
end