TrailerVote::Api
The TrailerVote Api gem is the official interface to communicate with the TrailerVote product service. It allows you to keep your code simple and not deal with the HTTP suite.
Installation
Add this line to your application's Gemfile:
gem 'trailer_vote-api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install trailer_vote-api
Usage
By default only the configuration api calls are available and you need to require which ever calls you want to make. A call always loads it dependencies. If you want to load everything you can require 'trailer_vote/api/autoload'
.
In order to call any of the APIs, you need to configure the api first:
key = '<TrailerVote API Client key>'
secret = '<TrailerVote API Client secret>'
url = '<TrailerVote API environment url>'
configuration = TrailerVote::Api.configure(url: url, key: key, secret: secret)
# => TrailerVote::Api::Configuration
The TrailerVote API Client for Ruby uses a lazy chainable API and does NOT make any requests until it's absolutely necessary. It is recommended that you re-use the configuration instance, as well as other results, in order to reduce network requests.
The common interface is:
#call(*args)
: Make the call and return an object that has results#data
: Return the inner data (#to_h
) without the wrapping key#to_i
: Return the HTTP status code#to_h
: Return the response (#call
), parsed (if parsable, like JSON) and validated (according to the media type)#etag
: Return the HTTP ETag header value, if any#links
: Return the HTTP Link header / inner_links
asLinks
object
Unless data is being posted, #call
is not necessary:
configuration = TrailerVote::Api.configure(url: url, key: key, secret: secret)
configuration.links
# => TrailerVote::Api::Links # Makes the HTTP call if necessary
In case of an error, a TrailerVote::Api::Error
is raised, with subclasses defining what went wrong. If the API gives back an error (HTTP status (400..599)
), the error is parsed and turned into a ErrorsResponse < Error
error.
Interface
Only the call available to the current link in the chain, if required
are available on each object.
configuration
You don't need to require this, it's always loaded.
require 'trailer_vote/api/configuration'
configuration = TrailerVote::Api.configure(key: '', secret: '', url: '')
# => TrailerVote::Api::Configuration
configuration.product.lookup
Used to lookup products by authority:identifier pairs. If found, returns the actual Product::Find
.
The data
argument is wrapped in { product_identifiers: data }
and then needs to match application/vnd.trailervote.product.lookup.v1+json
require 'trailer_vote/api/product/lookup'
lookup = configuration.product.lookup
# => TrailerVote::Api::Product::Lookup
lookup.call(data: [{ authority: 'imdb', identifier: 'tt01010101' }, { authority: 'tmdb', identifier: '12345678' }])
# => TrailerVote::Api::Product::Find
configuration.product.update
Used to update a product. Is only available on Product::Find
, because we require updates to be non-stale, that is you need to ensure that you are the last one updating the product, so merging data can be done correctly.
The data
argument is wrapped in { product: data }
and then needs to match application/vnd.trailervote.product.v2+json
require 'trailer_vote/api/product/lookup'
require 'trailer_vote/api/product/update'
lookup = configuration.product.lookup
product = lookup.call(data: [{ authority: 'imdb', identifier: 'tt01010101' }])
# => TrailerVote::Api::Product::Find
current_product_data = product.data
next_product_data = make_changes_to_product_data(current_product_data)
product.update.call(data: next_product_data)
# => TrailerVote::Api::Product::Find
If the update call fails with a 409 Conflict
or 412 Precondition Failed
, it means the product was updated in the meanwhile. You want to fetch the product again by doing another lookup and then running your strategy again.
configuration.product.create
Creating a product is similar to looking up a product. If successful, returns an actual Product::Find
.
The data
argument is wrapped in { product: data }
and then needs to match application/vnd.trailervote.product.v2.create+json
require 'trailer_vote/api/product/create'
configuration.product.create(data: { title: 'My product', ... })
# => TrailerVote::Api::Product::Find
configuration.product.<>.video.create
To attach an video to a product, you first need to find the product. This can be done by:
configuration.product.create
: creating a new productconfiguration.product.lookup
: looking up an existing product
Once you have it, the video operations are available on the result.
The data
argument is wrapped in { product_video: data }
and then needs to match application/vnd.trailervote.product.video.v1.create+json
require 'trailer_vote/api/product/lookup'
require 'trailer_vote/api/product/video/create'
product = configuration.product.lookup.call(data: [{ authority: 'imdb', identifier: 'tt01010101' }])
# => TrailerVote::Api::Product::Find
product.video.create(data: { source_url: '', ... })
# => TrailerVote::Api::Product::Video::Find
You can see in this example the product
result is cached in a variable, so that if you want to create many videos, the product isn't looked up each call.
configuration.product.<>.image.urls
Gets all the image urls for a product
configuration.product.<>.video.create
To attach an video to a product, you first need to find the product. This can be done by:
configuration.product.create
: creating a new productconfiguration.product.lookup
: looking up an existing product
Once you have it, the video operations are available on the result.
The data
argument is wrapped in { product_video: data }
and then needs to match application/vnd.trailervote.product.video.v1.create+json
require 'trailer_vote/api/product/lookup'
require 'trailer_vote/api/product/video/create'
product = configuration.product.lookup.call(data: [{ authority: 'imdb', identifier: 'tt01010101' }])
# => TrailerVote::Api::Product::Find
product.video.create(data: { source_url: '', ... })
# => TrailerVote::Api::Product::Video::Find
You can see in this example the product
result is cached in a variable, so that if you want to create many videos, the product isn't looked up each call.
configuration.product.<>.video.urls
Gets all the image urls for a product
configuration.product.<>.place.link
Links a place to a product
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can
also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the
version number in version.rb
, and then run bundle update trailer_vote-api
in any repository that depends on
this gem. If you have push rights, you may call bundle exec rake release
to create a new git tag, push
git commits and tags, and push the .gem
file to the rubygems gem server.
Contributing
Bug reports and pull requests are welcome on GitHub at TrailerVote/trailervote-api-clients