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.
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
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.
Or edit an existing app
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.
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
.
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.
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)
By default, Betsy handles the refreshing of authentication tokens for you.
# 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 })
The gem is available as open-source under the terms of the MIT License.
If you would like to contribute to this gem feel free to open issues or fork this repository and open a pull request.
Thanks to Will and Mark for answering my endless supply of questions when creating this gem.