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

After running the generator and migrating, open config/initializers/betsy.rb and set your API key and redirect url to the correct values.

Now Betsy should be configured for use.

Getting Authenticated

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.

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.