Skip to content

Latest commit

 

History

History
92 lines (63 loc) · 3.36 KB

general_overview.md

File metadata and controls

92 lines (63 loc) · 3.36 KB

General Overview

The different APIs accessible by this gem are:

In spite of having each their own specification, they all share some basics listed here.

API key usage

All APIs can be initialized by passing the API key in the new method

BestBuy::Products.new(your_api_key)

But the key can also be set up in a configure method available for the BestBuy module:

BestBuy.configure do |config|
  config.api_key = 'your_api_key'
end

Then, the next time you instantiate any API you can omit the key:

BestBuy::Products.new

For Ruby on Rails projects you can run:

$ rails generate best_buy:config

To generate this file: config/initializers/best_buy.rb, where you can write the configuration code.

For non Ruby on Rails projects, you can still write the configuration code wherever you like, as long as you make sure it runs before trying to access the APIs.

Common interface

This method can be used with any of the APIs:

get_all(search_query:, pagination:)

alias: index

Retrieves a collection of items (these depend on the API). These items will be filtered by search_query and limited by pagination.

Params:

  • search_query: A string representing the query added to the URL to filter the items (See Search Techniques in the Best Buy API reference). Optional.
  • pagination: See Pagination. Optional.

Returns: a CollectionsResponse object

search_query = '(active=true)'
pagination_params = { page: 2, page_size: 20 }

BestBuy::Categories.new(your_api_key).get_all(search_query: search_query, pagination: pagination_params)

Collections response

Every request made that returns a collection of items (no matter what kind of item) will return an object called CollectionsResponse. This object contains two attributes:

  • header
  • collection

The collection will contain a list of objects of the requested collection (Product, Store, etc).

The header will be a CollectionHeader object which will contain some metadata of the request itself. Its attributes include:

  • canonical_url: the non-server part of the query
  • current_page: the page being returned
  • partial: flag indicating whether or not the query returned only partial results (in the event of a timeout)
  • from: the index of the first item returned on the current page
  • to: the index of the last item returned on the current page
  • total: the total number of items returned by the query
  • total_pages: the number of pages required to list all items
  • query_time: the time required to search the database
  • total_time: the time required to parse, search, format and return results

Pagination

Best Buy APIs accept pagination parameters to control the amount of results returned. That's why for the get_all method, for example, there's an optional pagination parameter, which consists of a hash with two also optional keys:

  • :page: number of the page of results you’d like returned
  • :page_size: amount of results per page (default: 10, max: 100)

Example:

pagination_params = { page: 3, page_size: 50 }

BestBuy::Stores.new(your_api_key).get_all(pagination: pagination_params)