= Vimeo API Gem

This gem implements a full-featured ruby interface for the Vimeo API.

Vimeo's API documentation is, in my opinion, pretty poor. I've done my best to implement all the functions that are described {here}[http://vimeo.com/api-docs/advanced-api-docs.html]. There are some extra functions described {here}[http://vimeo.com/api/sandbox], but I can't be 100% sure what the correct parameters are for each method, so I'm going to omit them for the time being.

== Install

If you haven't already, add github's gem server to your sources:

  gem sources -a http://gems.github.com

Then, it's as easy as:

  sudo gem install matthooks-vimeo

Add the gem plugin to your Rails project by adding the following to your @environment.rb@ file:

  config.gem "matthooks-vimeo", :lib => "vimeo"

== Use

There are two modules:

  Vimeo::Simple
  Vimeo::Advanced

== Simple API

The wrapper for the Simple API consists of the following classes and methods:

=== Vimeo::Simple::User

  Vimeo::Simple::User.info(username)
  Vimeo::Simple::User.clips(username)
  Vimeo::Simple::User.likes(username)
  Vimeo::Simple::User.appears_in(username)
  Vimeo::Simple::User.all_clips(username)
  Vimeo::Simple::User.subscriptions(username)
  Vimeo::Simple::User.albums(username)
  Vimeo::Simple::User.channels(username)
  Vimeo::Simple::User.groups(username)
  Vimeo::Simple::User.contacts_clips(username)
  Vimeo::Simple::User.contacts_like(username)

=== Vimeo::Simple::Clip

  Vimeo::Simple::Clip.info(video_id)

=== Vimeo::Simple::Activity

  Vimeo::Simple::Activity.user_did(username)
  Vimeo::Simple::Activity.happened_to_user(username)
  Vimeo::Simple::Activity.contacts_did(username)
  Vimeo::Simple::Activity.happened_to_contacts(username)
  Vimeo::Simple::Activity.everyone_did(username)

=== Vimeo::Simple::Group

  Vimeo::Simple::Group.clips(groupname)
  Vimeo::Simple::Group.users(groupname)
  Vimeo::Simple::Group.info(groupname)

=== Vimeo::Simple::Channel

  Vimeo::Simple::Channel.clips(channelname)
  Vimeo::Simple::Channel.info(channelname)

=== Vimeo::Simple::Album

  Vimeo::Simple::Album.clips(album_id)
  Vimeo::Simple::Album.info(album_id)

== Advanced API

The classes in Vimeo::Advanced must be instantiated with an your application's api key and secret. For example,

  vimeo_video = Vimeo::Advanced::Video.new("api_key", "secret")

Then you can make calls on the instance:

  vimeo_video.get_list("matthooks", :page => 2, :per_page => 50)

The wrapper for the Advanced API consists of the following classes and methods:

=== Vimeo::Advanced::Auth

  get_token(frob)
  get_frob
  check_token(auth_token)

=== Vimeo::Advanced::Test

  echo(options={})
  null(auth_token)
  login(auth_token)

=== Vimeo::Advanced::Video

  get_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0 })
  get_uploaded_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  get_appears_in_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  get_subscriptions_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  get_list_by_tag(tag, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })@
  get_like_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })@
  get_contacts_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  get_contacts_like_list(user_id, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  search(q, options={ :page => 1, :per_page => 25, :full_response => 0, :auth_token => nil })
  get_info(video_id, auth_token=nil)
  delete(video_id, auth_token)
  get_thumbnail_url(video_id, size=100)
  set_title(video_id, title, auth_token)
  set_caption(video_id, caption, auth_token)
  set_favorite(video_id, favorite, auth_token)
  add_tags(video_id, tags, auth_token)
  remove_tag(video_id, tag_id, auth_token)
  clear_tags(video_id, auth_token)
  add_cast(video_id, user_id, auth_token, options={})
  get_cast(video_id, auth_token=nil)
  remove_cast(video_id, user_id, auth_token)
  set_privacy(video_id, privacy, auth_token)
  get_comments_list(video_id)
  add_comment(video_id, comment_text, auth_token, options={})
  delete_comment(video_id, comment_id, auth_token)
  edit_comment(video_id, comment_id, comment_text, auth_token)

=== Vimeo::Advanced::Person

  find_by_user_name(username)
  find_by_email(find_email)
  get_info(user_id)
  get_portrait_url(user_id, options={})
  add_contact(user_id, auth_token)
  remove_contact(user_id, auth_token)
  get_upload_status(user_id, auth_token)
  add_subscription(user_id, type, auth_token)
  remove_subscription(user_id, type, auth_token)

=== Vimeo::Advanced::Contact

  get_list(user_id)

=== Vimeo::Advanced::Group

  get_members(group_id)

=== Vimeo::Advanced::Upload

  get_upload_ticket(auth_token)
  check_upload_status(ticket_id, auth_token)

== Todo

* Implement options that allow you to specify a format (xml, json, PHP). Right now this is slightly complicated by the fact that Vimeo returns text/html for json and not application/json, so HTTParty can't auto-detect the content-type.
* Better initialize method for the advanced api that takes the auth_token into account.
* Define a method that returns the correct form URL for uploading videos.
* video_set_privacy needs the ability to specify users.
* Some methods are not implemented by vimeo or don't seem to work.
* Input verification? The alternative is to just let vimeo handle it.
* May need to escape input in several cases
* More re-factoring.
* Tests

== Thanks to

* {HTTParty}[http://github.com/jnunemaker/httparty/tree/master]: Easily one of the best tools I have used since I started using Ruby.
* {Jeweler}[http://github.com/technicalpickles/jeweler/tree/master]: Great tool for creating gems for github.

=== Copyright (c) 2008 Matt Hooks. See LICENSE for details.