Betsy

Betsy is an unopinionated gem for using the Etsy API. Betsy is designed to be a 1-to-1 mapping of Etsy's API giving you access to all endpoints and all available data.

Installation

First, install Betsy by adding it to your gemfile:

gem 'betsy'

And then run:

bundle install

Next, you need to run the generator:

rails generate betsy:install

Running the generator will create an etsy_account model in your app as well as a migration for this model. The purpose of this model is to allow you to easily link and store an Etsy account. This model is used within the gem by providing the access_token and refresh_token needed with making calls that require authentication. You can add anything to this model as long as the original fields are left as-is. This may be useful if you wish your application to have relations with an Etsy account.

Finally, you need to run the migration:

rails db:migrate

Usage

First setup an Etsy developer account and create an app. Note, the process of getting an approveed app may take days and possible multiple attempts for clarity.

https://www.etsy.com/developers/register

Or edit an existing app

https://www.etsy.com/developers/your-apps

Set your Callback URLs to

http://localhost:3000/etsy_response_listener
https://YOUR_PRODUCTION_DOMAIN/etsy_response_listener

After running the generator, migrating, and configuring your app with Etsy, Your API key and Callback URL values are referred to in: config/initializers/betsy.rb It is currently configured to look for the following ENV variables. Be sure your ETSY_CALLBACK_URL_BASE matches your Callback URL exactly (minus /etsy_response_listener) I like the gem dotenv. Then I only have to edit .env to look like this:

ETSY_API_KEY=YOUR_PRIVATE_API_KEY
ETSY_CALLBACK_URL_BASE=http://localhost:3000 # do not add /etsy_response_listener

Be sure to configure your production environment to use https://YOUR_PRODUCTION_DOMAIN/ for ETSY_CALLBACK_URL_BASE

Now Betsy should be configured for use.

Getting Authenticated

You should only have to do this once per database for your app. To begin going through the authentication process you will first start by using Betsy to generate an authorization URL:

Betsy.authorization_url

By default authorization_url requests access for all scopes, if you would prefer more restrictive scopes can also be passed to authorization_url like so:

Betsy.authorization_url(scope: ["address_r", "address_w"])

Going to the URL generated by authorization_url will ask the user to grant access to their account. Then they will be redirected back to your site. This will update the EtsyAccount with the access_token and refresh_token.

Making Unauthenticated API Requests

Betsy is made to mimic Etsy's API. To make a call you will use the Betsy class for that category, i.e. for ShopListing Inventory the class would be Betsy::ShopListingInventory. All the methods listed in the Etsy documentation are available to use by calling that method on the category class following proper Ruby syntax, i.e. Betsy::ShopListingInventory.get_listing_inventory. The only parameters for these methods are path parameters, such as shop_id or listing_id and these are passed in the order in which they appear in the URL. All other parameters can be passed as named parameters. Betsy handles your API key so this does not need to be passed to these methods.

Making Authenticated API Requests

To make an API request that is authenticated follow the instructions above but also pass a named parameter etsy_account with an EtsyAccount model.

Betsy::UserAddress.get_user_addresses(etsy_account: EtsyAccount.first)

Refreshing Access Tokens

By default, Betsy handles the refreshing of authentication tokens for you.

Example Usage

# Find a shop and its ID
shops = Betsy::Shop.find_shops('some totally unique shop name')
shop = shops.first
platform_shop_id = shop.shop_id

# All of the things
puts shop.inspect

# Get some listings
listings_per_batch = 20
listings_offset = 0
listings = Betsy::ShopListing.find_all_active_listings_by_shop(platform_shop_id, { limit: listings_per_batch, offset: listings_offset })
listing = listings.first
platform_listing_id = listing.listing_id

# Get some images
images = Betsy::ShopListingImage.get_listing_images(platform_shop_id, platform_listing_id)

# Get some reviews
reviews_per_batch = 20
reviews_offset = 0
betsy_reviews = Betsy::Review.get_reviews_by_listing(listing.platform_listing_id, { limit: reviews_per_batch, offset: reviews_offset })

License

The gem is available as open-source under the terms of the MIT License.

Contributing

If you would like to contribute to this gem feel free to open issues or fork this repository and open a pull request.

Special thanks.

Thanks to Will and Mark for answering my endless supply of questions when creating this gem.

billzajac/betsy