TrailerVote::Api

Build Status Gem Version Maintainability Depfu

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 as Links 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 product
  • configuration.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 product
  • configuration.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

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