Fera API Ruby Client

Welcome to the Fera API gem for Ruby. This gem is Fera's official Ruby SDK and make it easy to interact with the Fera API.

Fera API Developer Docs and API Reference can be found at: https://developers.fera.ai

Installation

Install the gem and add to the application's Gemfile by executing:

  gem 'fera-api'

Configuration

The Fera::API gem accepts 2 both Secret/API Key authentication to authenticate against your own Fera store/account, or Auth Token authentication to authenticate against a Fera store/account that you have access to with your Fera App.

You can learn more about how to obtain your API key or obtain an auth token in our developer docs.

Configuring for your own Fera store/account

Assuming you're using the dotenv gem (recommended) simply set the FERA_SECRET_KEY env variable to your store's secret key, then run:

Fera::API.configure(ENV['FERA_SECRET_KEY'])

If you're not using the dotenv then just run Fera::API.configure("sk_your_secret_key") directly.

Rails Setup

If you're using rails the best way to configure the gem is to add the following to your config/initializers/fera.rb:

Fera::API.configure(ENV['FERA_SECRET_KEY'])

(And of course set the ENV variable)

Configuring as a Fera App

If you're building a Fera Partner App, you're going to need to authenticate like this instead:

Fera::API.configure(store_auth_token) do
  # Some code here that will run against the store which you're authenticated against
end

store_auth_token is what you get after successfully completing OAuth flow for a Fera account/store./

This gem also comes with a helper class for working with an app:

$fera_app = Fera::App.new(ENV['FERA_CLIENT_ID'], ENV['FERA_CLIENT_SECRET'])

We recommend assigning this to a global variable since the methods in the Fera::App instance won't vary from Fera store/account to store/account.

Usage

If you've configured the gem globally because you're only working with 1 store, you can now just call Fera models just like you would call a Rails model:

Fera::Review.all # Returns collection of reviews.

Partner App Usage

If you're building an app and want to run a method against a specific store only, you can run the same code but within the Fera::API block:

Fera::API.configure(store_auth_token) do
  Fera::Review.all # Returns collection of reviews.
end

If you're building a partner app on Ruby, you might also want to check out the Fera OmniAuth Strategy gem that will make it easy to connect our app to Fera to get an auth token and start using this API.

Examples

Reviews

See https://developers.fera.ai/reference/reviews

List all reviews

Fera::Review.all # Returns collection of reviews.

List a product's reviews

Fera::Review.for_product(product_id: "123") # Returns collection of reviews for product with id "123".

List a customer's reviews

Fera::Review.where(customer_id: "123")

Create a review

Fera::Review.create(
  product_id: "123",
  rating: 5,
  body: "This is a great product!"
)

Retrieve specific review

Fera::Review.find("frev_abc123") # Returns review with id "frev_abc123".

Update review

review.update(body: "This is a new review body")
# OR:
review.body = "This is a new review body"
review.save!

Delete review

review.destroy!

Photos and Videos (Media)

A media object may either be a photo or a video.

See https://developers.fera.ai/reference/media

List all photos and videos

Fera::Media.all # Returns collection of reviews.

List a product's photos and videos

Fera::Media.for_product(product_id: "123") # Returns collection of reviews for product with id "123".

Create photo

Fera::Photo.create(
  product_id: "123",
  file: "path/to/file",
  caption: "This is my photo."
)

Create video

Fera::Video.create(
  product_id: "123",
  file: "path/to/file",
  caption: "This is my video."
)

Retrieve specific photo or video

media = Fera::Media.find("fmed_abc123") # Returns photo or video with id "frev_abc123".
puts "URL to #{ media.is_photo? ? 'photo' : 'video' }: #{ media.url }"

Update photo or video

media.update(caption: "This is a new media caption")
# OR:
media.caption = "This is a new media caption"
media.save!

Delete photo or video

media.destroy!

Customers

See https://developers.fera.ai/reference/customers

List all customers

Fera::Customer.all # Returns collection of customers.

Create customer

Fera::Customer.create(
  name: "Michael Bluth",
  email: "michael.bluth@example.com",
  external_id: "shopify_customer_1234"
)

Retrieve specific customer

Fera::Customer.find("fcus_abc123") # Returns customer with id "fcus_abc123".

Update customer

customer.update(name: "Tobias Funke")
# OR:
customer.name = "Tobias Funke"
customer.save!

Delete customer

customer.destroy!

Ratings

See https://developers.fera.ai/reference/ratings

Retrieve a specific product's rating

rating = Fera::Rating.for_product("product_id_1")
puts "Product has #{ rating.count } reviews with an average rating of #{ rating.average }/5."

List a list of product ratings

Fera::Rating.for_products(["product_id_1", "product_id_2", "product_id_3"]) # Returns collection of ratings for product with id "123".

Retrieve the store's overall rating

rating = Fera::Rating.for_store
puts "This store is rated #{ rating.average }/5 on average by #{ rating.count } customer(s)."

Other resources to check out

You can use some of the other resources the same way:

See our developer API reference for all filters, methods and options.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/feracommerce/fera-api-ruby.

How to contribute

To contribute to the repository:

Fork the repository.
Clone the forked repository locally.
Create a branch descriptive of your work. For example "my_new_feature_xyz".
When you're done work, push up that branch to your own forked repository (not the main one).
Visit https://github.com/feracommerce/fera-api-ruby and you'll see an option to create a pull request from your forked branch to the master. Create a pull request.

License

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