Vm

Vm lets you interact with many resources provided by Vimeo API V3.

Build Status Code Climate Coverage Status Dependency Status

channel = Vm::VimeoResource.new url: 'vimeo.com/remhq'
channel.id #=> 'UC7eaRqtonpyiYw0Pns0Au_g'
channel.title #=> "remhq"
channel.description #=> "R.E.M.'s Official Vimeo Channel"

video = Vm::VimeoResource.new url: 'youtu.be/Kd5M17e7Wek'
video.id #=> 'Kd5M17e7Wek'
video.title #=> "R.E.M. - Tongue (Video)"
video.description #=> "© 2006 WMG\nTongue (Video)"

 = Vm::VimeoAccount.new auth_params
.email #=> '[email protected]'

 = Vm::VimeoAccount.new auth_params
.perform! :like, :video, 'Kd5M17e7Wek' # => adds 'Tongue' to your 'Liked videos'
.perform! :subscribe_to, :channel, 'UC7eaRqtonpyiYw0Pns0Au_g' # => subscribes to R.E.M.’s channel

The full documentation is available at rubydoc.info.

Available classes

Vm exposes three different resources provided by Vimeo API V3: Vimeo Accounts, Vimeo Accounts and Vimeo Resources.

Vimeo accounts

Use Vm::VimeoAccount to send and retrieve data to Vimeo, impersonating an existing Vimeo account. Available methods:

  • email: returns the email of a Vimeo account
  • name: returns the name of a Vimeo account

These methods require user authentication (see below).

Vimeo accounts

Use Vm::VimeoAccount to send and retrieve data to Vimeo, impersonating an existing Vimeo account. Available methods:

  • perform!: executes promotion actions such as: liking a video, subscribing to a channel

These methods require user authentication (see below).

Vimeo resources

Use Vm::VimeoResource to retrieve read-only information about public Vimeo channels and videos. Available methods:

  • id: returns the unique identifier of a Vimeo channel/video
  • title: returns the title of a Vimeo channel/video
  • description: returns the description of a Vimeo channel/video
  • thubmnail_url: returns the URL of the thumbnail of a Vimeo channel/video

These methods require do not require user authentication.

Authentication

In order to use Vm you must register your app in the Vimeo Developers Console:

  1. Create a new app and enable access to Vimeo+ API and Vimeo Data API V3
  2. Generate a new OAuth client ID (web application) and write down the client ID and client secret
  3. Generate a new Public API access key (for server application) and write down the server key

Run the following command to make these tokens available to Vm:

require 'vm'
Vm.authenticate_with client_id: '...', client_secret: '...', server_key: '...'

replacing the ellipses with the values from the Vimeo Developers Console.

For actions that impersonate a Vimeo or Vimeo account, you also need to obtain authorization from the owner of the account you wish to impersonate:

  1. In your web site, add a link to the Vimeo's OAuth login page. The URL is:

    Vm::VimeoAccount.oauth_url(url) # to impersonate a Vimeo Account
Vm::VimeoAccount.oauth_url(url) # to impersonate a Vimeo Account

  2. Upon authorization, the user is redirected to the URL passed as an argument, with an extra 'code' query parameter which can be used to impersonate the account:

     = Vm::VimeoAccount.new(code: code, redirect_uri: url) # to impersonate a Vimeo Account
 = Vm::VimeoAccount.new(code: code, redirect_uri: url) # to impersonate a Vimeo Account

  3. To prevent the user from having to authorize the app every time, store the account’s refresh_token in your database:

    refresh_token = .credentials[:refresh_token] # Store to your DB

  4. To impersonate an account that has already authorized your app, just use the refresh_token:

     = Vm::VimeoAccount.new(refresh_token: refresh_token) # to impersonate a Vimeo Account
 = Vm::VimeoAccount.new(refresh_token: refresh_token) # to impersonate a Vimeo Account

Remember that the redirect URL you use in the app must also be registered in the Vimeo Developers Console. Also, remember to set a Product name for your app in the Vimeo Developers Console, under API & Auth > Consent screen.

How to install

To install on your system, run

gem install vm

To use inside a bundled Ruby project, add this line to the Gemfile:

gem 'vm', '~> 0.1.0'

The vm gem follows Semantic Versioning. Any new release that is fully backward-compatible bumps the patch version (0.0.x). Any new version that breaks compatibility bumps the minor version (0.x.0)

Indicating the full version in your Gemfile (major.minor.patch) guarantees that your project won’t occur in any error when you bundle update and a new version of Vm is released.

Why you should use Vm…

… and not vimeo_it? Because vimeo_it does not support Vimeo API V3 and the previous version has already been deprecated by Vimeo and will soon be dropped.

… and not Vimeo Api Client? Because Vimeo Api Client is poorly coded, poorly documented and adds many dependencies, bloating the size of your project.

… and not your own code? Because Vm is fully tested, well documented, has few dependencies and helps you forget about the burden of dealing with Vimeo API!

How to test

To run the tests, you must give the test app permissions to access your Vimeo and Vimeo accounts. They are free, so feel free to create a fake one.

  1. Run the following commands in a ruby session:

    require 'vm'
Vm::VimeoAccount.oauth_url  # => "https://accounts.google.com/o..."

  2. Copy the last URL in a browser, and accept the terms. You will be redirected to a URL like http://example.com/?code=ABCDE

  3. Copy the code parameter (ABCDE in the example above) and run:

     = Vm::VimeoAccount.new code: 'ABCDE'
.credentials[:refresh_token]

  4. Copy the token returned by the last command (something like 1AUJZh2x1...) and store it in an environment variable before running the test suite:

    export GOOGOL_TEST_GOOGLE_REFRESH_TOKEN="1AUJZh2x1..."

  5. Repeat all the steps above replacing VimeoAccount with VimeoAccount to authorize access to your Vimeo account:

    export GOOGOL_TEST_YOUTUBE_REFRESH_TOKEN="2B6T5x23..."

  6. Finally run the tests running rspec or rake. If you prefer not to set environment variables, pass the refresh token in the same line:

    GOOGOL_TEST_GOOGLE_REFRESH_TOKEN="1AUJZh2x1..." GOOGOL_TEST_YOUTUBE_REFRESH_TOKEN="2B6T5x23..." rspec

How to contribute

Don’t hesitate to send code comments, issues or pull requests through GitHub!

All feedback is appreciated. A vm of thanks! :)