The official TradeGecko API RubyGem
This library provides a Ruby interface to publicly available (beta) API for TradeGecko.
If you are unfamiliar with the TradeGecko API, you can read the documentation located at https://developer.tradegecko.com
Add this line to your application's Gemfile:
gem 'gecko-ruby'
And then execute:
$ bundle
Or install it yourself as:
$ gem install gecko-ruby
client = Gecko::Client.new(CLIENT_ID, CLIENT_SECRET)
client.access_token = existing_access_token
products = client.Product.where(q: "Gecko")
#=> [<Gecko::Record::Product id=1 name="Geckotron">, <Gecko::Record::Product id=3 name="Green Gecko">]
client = Gecko::Client.new(CLIENT_ID, CLIENT_SECRET)
client.authorize_from_existing(PRIVILEGED_ACCESS_TOKEN, nil, nil)
products = client.Product.where(q: "Gecko")
#=> [<Gecko::Record::Product id=1 name="Geckotron">, <Gecko::Record::Product id=3 name="Green Gecko">]
client.Product.find(123)
#=> <Gecko::Record::Product id=123 name="Geckotron">
client.Product.find_many(123, 124)
#=> [<Gecko::Record::Product id=123 name="Geckotron">, <Gecko::Record::Product id=124 name="Salamander">
client.Product.where(ids: [123, 124])
#=> [<Gecko::Record::Product id=123 name="Geckotron">, <Gecko::Record::Product id=124 name="Salamander">
The Gecko gem ships with a basic identity map
client.Product.find(123)
# Makes an API request
client.Product.find(123)
# Returned from identity map on second request, no API request
client.Product.fetch(123)
# Does not use identity map and makes request regardless
client.Product.find_many([123, 124])
# Will return 123 from memory and make request for 124
client.Product.where(ids: [123, 124])
# Does not use identity map and makes request regardless
You can create new records by calling build
on the appropriate adapter.
geckobot = client.Product.build(name: "Geckobot", product_type: "Robot")
#=> <Gecko::Record::Product id=nil name="Geckobot" product_type: "Robot">
geckobot.persisted?
#=> false
You can persist new records by calling save
.
geckobot = client.Product.build(name: "Geckobot", product_type: "Robot")
#=> <Gecko::Record::Product id=nil name="Geckobot" product_type: "Robot">
geckobot.persisted?
#=> false
geckobot.save # Persists to API
#=> true
geckobot
#=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robot">
You can also create new records from inside a parent object.
variant = product.variants.build(name: "Geckobot", sku: "ROBO")
#=> <Gecko::Record::Variant id=nil product_id=123 name="Geckobot" sku: "ROBO">
variant.persisted?
#=> false
variant.save #=> Persists to API
#=> true
variant
#=> <Gecko::Record::Variant id=125 product_id=123 name="Geckobot" sku: "ROBO">
geckobot = client.Product.find(124)
#=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robot">
geckobot.persisted?
#=> true
geckobot.product_type = "Robo-boogie"
geckobot.save # Persists to API
#=> true
geckobot
#=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robo-boogie">
Some records support being saved inside of their parents. A good example is creating a Sales Order and it's line items.
order = client.Order.build(company_id: 123, shipping_address_id: 123)
order.order_line_items.build(quantity: 1, variant_id: 123, price: 10.5)
order.order_line_items.build(quantity: 2, variant_id: 124, price: 11.0)
order.save # Persists to API
#=> true
order.order_line_items
#=> [<Gecko::Record::OrderLineItem id=125 variant_id=123 quantity: 1 price: '10.5'>,
<Gecko::Record::OrderLineItem id=126 variant_id=124 quantity: 2 price: '11.0'>]
This also works when adding new items to an existing order.
order = client.Order.find(123)
order.order_line_items.build(quantity: 1, variant_id: 123, price: 10.5)
order.order_line_items.build(quantity: 2, variant_id: 124, price: 11.0)
order.save # Persists to API
#=> true
order.order_line_items
#=> [<Gecko::Record::OrderLineItem id=125 variant_id=123 quantity: 1 price: '10.5'>,
<Gecko::Record::OrderLineItem id=126 variant_id=124 quantity: 2 price: '11.0'>]
N.B. Only creation of embedded objects works at this time.
Updating/Deleting embedded items must still be done by calling save/destroy
on each of the child objects themselves.
geckobot = client.Product.find(124)
#=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robot">
geckobot.persisted?
#=> true
geckobot.name = nil
geckobot.save # Attempts to persist to API
#=> false
geckobot.valid?
#=> false
geckobot.errors
#=> #<Gecko::Errors:0x007ff46d961810 @base=#<Gecko::Record::Base:0x007ff46d96aaa0 id: 124, name: nil>, @messages={:name=>["can't be blank"]}>
The Gecko gem supports instrumentation via AS::Notifications.
You can subscribe to API calls by subscribing to 'request.gecko'
notifications
ActiveSupport::Notifications.subscribe('request.gecko') do |name, start, finish, id, payload|
# Do Something
end
The gem comes with a default LogSubscriber
that outputs API requests in an ActiveRecord style.
This is disabled by default and can be included by calling Gecko.enable_logging
.
The Gecko gem stores a copy of the last API response per adapter. You can use this to access headers such as cache controls or current API limit usages.
client.Product.find(124)
client.Product.last_response.headers['X-Rate-Limit-Limit']
#=> '300'
client.Product.last_response.headers['X-Rate-Limit-Remaining']
#=> '290'
client.Product.last_response.headers['X-Rate-Limit-Reset']
#=> '1412079600'
A compatibility shim for the Liquid templating language is distributed, but not loaded by default.
This can be enabled via Gecko.install_liquid_shim
- Deleting records
- Complete record collection
- Handle more API Errors
- Clean up Access Token management
- Fork it ( https://github.com/tradegecko/gecko/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request