oEmbed’le Tanışalım
FriendFeed kullanıyorsanız resimdeki manzarayla sık sık karşılaşmışsınızdır.
FriendFeed, kullanıcı yeni bir feed eklediği zaman metin içerisinde geçen linklerle ilgili resimleri (burda youtube.com videosunun thumb resmi) bulup feede güzellik katıyor. Peki bunu nasıl yapıyor? Belirtilen linkin neye ait olduğunu, linkteki hangi resmin önemli olduğunu nerden biliyor? İşte tam burda işin içine oEmbed giriyor.
Hızlıca anlatayım: oEmbed İstemci sitenin (burada FriendFeed) Sunucu siteden (burada Youtube.com) içerik bilgisi alması için oluşturulan protokoldür.
Bu protokol şöyle çalışıyor: Örnekte Youtube.com bahsi geçen videonun bulunduğu sayfasına aşağıdaki gibi iki meta-tag ilave ediyor:
<link rel="alternate" type="application/json+oembed" href="http://www.youtube.com/oembed?url=http%3A//www.youtube.com/watch?v%3DKrjCjJ57nro&format=json" title="Visages d'Art" /> <link rel="alternate" type="text/xml+oembed" href="http://www.youtube.com/oembed?url=http%3A//www.youtube.com/watch?v%3DKrjCjJ57nro&format=xml" title="Visages d'Art" />
Bunların her ikisi aynı işi görüyor. Ama birisi JSON diğeri ise XML sonuç döndürüyor.
JSON sonuç:
{
"version": "1.0",
"type": "video",
"provider_name": "YouTube",
"provider_url": "http://www.youtube.com/",
"author_name": "eggman913",
"author_url": "http://www.youtube.com/user/eggman913",
"title": "Visages d'Art",
"html": "
<object width=\"425\" height=\"344\">
<param name=\"movie\" value=\"http://www.youtube.com/v/KrjCjJ57nro&fs=1\"></param>
<param name=\"allowFullScreen\" value=\"true\"></param>
<param name=\"allowscriptaccess\" value=\"always\"></param>
<embed
src=\"http://www.youtube.com/v/KrjCjJ57nro&fs=1\"
type=\"application/x-shockwave-flash\"
width=\"425\" height=\"344\"
allowscriptaccess=\"always\"
allowfullscreen=\"true\">
</embed>
</object>",
"height": 344,
"width": 425
}
XML Sonuç:
<?xml version="1.0" encoding="utf-8"?> <oembed> <version>1.0</version> <type>video</type> <provider_name>YouTube</provider_name> <provider_url>http://www.youtube.com/</provider_url> <author_name>eggman913</author_name> <author_url>http://www.youtube.com/user/eggman913</author_url> <title>Visages d'Art</title> <html> <object width="425" height="344"> <param name="movie" value="http://www.youtube.com/v/KrjCjJ57nro&fs=1"></param> <param name="allowFullScreen" value="true"></param> <param name="allowscriptaccess" value="always"></param> <embed src="http://www.youtube.com/v/KrjCjJ57nro&fs=1" type="application/x-shockwave-flash" width="425" height="344" allowscriptaccess="always" allowfullscreen="true"> </embed> </object> </html> <height>344</height> <width>425</width> </oembed>
Bu çıktılar ışığında İstemci yazılım ilişkili içeriğin bilgilerine erişmiş oluyor.
Bu çıktıların ne olduğu, istemin nasıl yapılması gerektiği vs. hakkkında kafanızda çeşitli sorular doğmuştur. Biraz daha açalım.
oEmbed – Özellikler
API endpoint – sorguların yapıldığı URL veya URLlerdir. Sadece HTTP olmalıdır. HTTPS, FTP vs. olamaz. (http://www.youtube.com/oembed)
URL Scheme – Hangi içieriklere oEmbed servisi sunulduğunu gösteriri. (http://www.youtube.com/watch?v=*)
İstek
İstekler GET metoduyla olmalıdır. Tüm parametreler urlencoded olmalıdır. İstek parametreleri aşağıdaki gibidir:
url (zorunlu) – Hakkında bilgi istenen içeriğin URLi.
maxwidth (isteğe bağlı) – Gönderilen html içerik için maksimum genişlik.
maxheight (isteğe bağlı) – Gönderilen html içerik için maksimum genişlik.
format (isteğe bağlı) – Talep edilen istek için format (xml, json). Belirtilmediği zaman Sunucu site istenilen geçerli format döndüre bilir.
Örnek istek linki:
http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/&maxwidth=300&maxheight=400&format=json
Sunucu siteler format alanı parametre olarak değil de, API endpoint’in bir parçası olarak da sunabilirler:
http://www.flickr.com/services/oembed.xml veya http://www.flickr.com/services/oembed.json
Yanıt
Sunucu siteler yanıtları istenilen parametreye uygun olarak json veya xml formatında vermelidir. Parametreler aşağıdaki gibidir:
type (zorunlu) – Kaynağım türünü gösterir. photo, video, link veya rich olabilir. Her türün kendine özel zorunlu ve isteğe bağlı alanları vardır. Bunlar aşağıda belirteceğim.
version (zorunlu) – oEmbed sürüm numarasındır. 1.0 olmalıdır.
title (isteğe bağlı) – Kaynağa ait başlık
author_name (isteğe bağlı) – Kaynak sahibinin ismi
author_url (isteğe bağlı) – Kaynak sahibinin profil linki.
provider_name (isteğe bağlı) – Kaynak sağlayan ismi. Genelde site ismidir.
provider_url (isteğe bağlı) – Kaynak sağlayan linki. Genelde Sunucu site ismidir.
cache_age (isteğe bağlı) – İçeriğin saniye biriminden geçerlilik süresidir.
thumbnail_url (isteğe bağlı) – Thumbnail (küçük resim) yoludur.
thumbnail_width (isteğe bağlı) – Thumbnail genişliğidir. Belirtilirse thumbnail_url ve thumbnail_height de belirtilmelidir.
thumbnail_height (isteğe bağlı) – Thumbnail yüksekliğidir. Belirtilirse thumbnail_url ve thumbnail_width de belirtilmelidir.
Bunlardan başka her yanıt türü için özel parametreler de vardır:
Yanıt Türü: photo
Static resimler sunmak içindir.
url (zorunlu) – Resmin tam yoludur. Sadece http veya https ile başlaya bilir.
width (zorunlu) – Resmin piksel biriminden genişliğidir.
height (zorunlu) – Resmin piksel biriminden yüksekliğidir.
Yanıt Türü: video
Direk oynatılabilir videolar içindir. Genelde Flash video oynatıcı ile birlikte yüklenir.
html (zorunlu) – Embed video oynatıcılı HTMLdir. Padding ve Margin stilleri olmamalıdır.
width (zorunlu) – HTML genişliği
height (zorunlu) – HTML yüksekliği
Yanıt Türü: link
Bu yanıt türü içerik hakkında genel bilgiler (title ve author_name) almak için kullanılır. İstemci isterse içeriğin orinal adresine link verebilir.
Yanıt Türü: rich
Bu yanıt türü yukarıdaki yanıt türlerinin hiç birisine uymayan içerikler için zengin html sunar.
html (zorunlu) – Kaynak gösterimi için html. Padding veya Margin kullanılmamalıdır. İşaretleme (Kodlama) “XHTML 1.0 Basic” standartına uymalıdır.
width (zorunlu) – Gösterilecek HTML’in genişliği
height (zorunlu) – Gösterilecek HTML’in yüksekliği
Hata Mesajları
Sunucu Siteler hatalarla ilgili html durum kodları göndere bilirler:
404 Not Found – İstem sırasında belirtilen URL hatalı ise döndürülür.
501 Not Implemented – Sunucu site talep edilen formatı (xml veya json) desteklemiyorsa döndürülür.
401 Unauthorized – Bilgi istenen içeriğe erişim izni yoksa döndürülür.
oEmbed’e hızlı bir giriş yapmış olduk.
Sitenize bu özelliği katmak içi aşağıdaki PHP kütüphaneleri öneriliyor:
php-oembed (http://code.google.com/p/php-oembed/)
Services_oEmbed (http://pear.php.net/package/Services_oEmbed)
Bu protok hakkında daha geniş bilgi almak için İngilisce kaynak olan oembed.com sitesine bakınız.