oembed gem

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

oembed gem is a simple to use and slim (~150 LOC) library to work with oEmbed format. It has no external dependencies at runtime. All you need to have is Ruby itself.

The library shares a behaviour of oEmbed client with any Ruby object. Just include Oembed::Client into that object and you are good to go.

oembed gem is provider agnostic. It has no pre-configured providers. You can build a client for any oEmbed provider of the world :)

Installation

Add this line to your application's Gemfile:

gem 'oembed'

And then execute:

$ bundle

Or install it yourself as:

$ gem install oembed

Usage

You have to do a few things to build an oEmbed client with oembed gem.

• include Oembed::Client into your object,
• add instance method #endpoint_uri to that object. This method has to return a string with URI of oEmbed endpoint.

Lets start with a simple example. It will be a client for the awesome Speaker Deck. Note that we call the service class NameApi - this is to avoid clashing with gems (such as twitter) that may have classes named after the service.

require 'oembed'

class SpeakerDeckApi
  include Oembed::Client

  # Read more about endpoint on https://speakerdeck.com/faq#oembed
  def endpoint_uri
    'http://speakerdeck.com/oembed.json'
  end
end

That's it. Now you can use a method #fetch to get data from oEmbed enpoint of Speaker Deck.

client = SpeakerDeckApi.new
client.fetch('https://speakerdeck.com/u/soulim/p/rails')

The method #fetch will return a hash with oEmded data.

{
  "type" => "rich",
  "version" => 1.0,
  "provider_name" => "Speaker Deck",
  "provider_url" => "https://speakerdeck.com/",
  "title" => "Локализация приложения на базе Rails. Личный опыт и советы",
  "author_name" => "Alex Soulim",
  "author_url" => "https://speakerdeck.com/u/soulim",
  "html" => "<iframe style=\"border:0; padding:0; margin:0; background:transparent;\" mozallowfullscreen=\"true\" webkitallowfullscreen=\"true\" frameBorder=\"0\" allowTransparency=\"true\" id=\"presentation_frame_4fd3874cebb4b2001f0277e5\" src=\"//speakerdeck.com/embed/4fd3874cebb4b2001f0277e5\" width=\"710\" height=\"596\"></iframe>\n",
  "width" => 710,
  "height" => 596
}

oembed gem supports JSON and XML response formats. Here is an example of client for XML endpoint.

require 'oembed'

class FlickrApi
  include Oembed::Client

  def endpoint_uri
    'http://www.flickr.com/services/oembed.xml'
  end
end

client = FlickrApi.new
client.fetch('http://www.flickr.com/photos/alex_soulim/3593916989')

It will return:

{
  "type"=>"photo",
  "title"=>"IMG_2072",
  "author_name"=>"Alex Soulim", "author_url"=>"http://www.flickr.com/photos/alex_soulim/",
  "width"=>"683",
  "height"=>"1024",
  "url"=>"http://farm4.staticflickr.com/3618/3593916989_3d8aa991ea_b.jpg",
  "web_page"=>"http://www.flickr.com/photos/alex_soulim/3593916989/",
  "thumbnail_url"=>"http://farm4.staticflickr.com/3618/3593916989_3d8aa991ea_s.jpg",
  "thumbnail_width"=>"75",
  "thumbnail_height"=>"75",
  "web_page_short_url"=>"http://flic.kr/p/6tzLj2",
  "license"=>"All Rights Reserved",
  "license_id"=>"0",
  "version"=>"1.0",
  "cache_age"=>"3600",
  "provider_name"=>"Flickr",
  "provider_url"=>"http://www.flickr.com/"
}

You can make requests with additional parameters. Let's build a client for Instagram and use :maxwidth parameter.

require 'oembed'

class InstagramApi
  include Oembed::Client

  def endpoint_uri
    'http://api.instagram.com/oembed'
  end
end

client = InstagramApi.new
client.fetch('http://instagr.am/p/BUG/', maxwidth: 300)

If you need to always customise the fetch with additional parameters this can be done by providing a fetch method in the service class. In this example we are adding a maxwidth parameter to the request.

require 'oembed'

class YoutubeApi
  include Oembed::Client

  def endpoint_uri
    'https://www.youtube.com/oembed'
  end

  def fetch(url, options={})
    super url, options.merge(maxwidth: 620)
  end
end

client = YoutubeApi.new
client.fetch('https://www.youtube.com/watch?v=_DRNgL76OLc')

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Supported Ruby versions

This library is tested against the following Ruby implementations:

• MRI Ruby 2.1
• MRI Ruby 2.0
• JRuby