Pedoman Kompatibilitas Mundur

Setiap permintaan YouTube Data API dapat menentukan versi API yang harus digunakan YouTube untuk menangani permintaan tersebut. Jika permintaan tidak menentukan versi API, YouTube akan menggunakan versi API terlama yang didukung untuk menangani permintaan tersebut. Versi tertua yang didukung saat ini adalah 1. Perhatikan karakteristik nomor versi API berikut:

  • YouTube dapat merilis update ke versi API tertentu yang rilisnya tidak diberi nomor versi baru. Update yang kompatibel dengan versi sebelumnya ini dapat mencakup fitur API opsional, perbaikan bug, atau keduanya.

  • Penambahan nomor versi API mengidentifikasi rilis yang berisi perubahan yang tidak kompatibel dengan versi API sebelumnya.

Dokumen ini menentukan pedoman kompatibilitas mundur untuk update ke versi API tertentu, item pertama yang tercantum di atas. Panduan ini berupaya membedakan antara jenis fungsi API berikut:

  • Panduan ini mengidentifikasi fungsi API yang dapat berubah meskipun Anda tidak mengubah versi API yang harus digunakan untuk menangani permintaan API. Kode Anda harus menangani perubahan ini tanpa mengalami error. Misalnya, jika YouTube menambahkan tag XML baru ke respons API, kode Anda harus mengabaikan tag tersebut.

  • Panduan ini juga menentukan fungsi API yang tidak ingin diubah oleh YouTube saat mengupdate versi API tertentu. Dengan kata lain, Anda hanya boleh mengharapkan fungsi tersebut berubah jika YouTube merilis versi API baru, dan kode Anda tidak perlu mencoba menangani jenis perubahan ini.

Tentang dokumen ini

Dokumen ini berisi bagian-bagian berikut:

  • Bagian Permintaan API menentukan panduan kompatibilitas mundur yang terkait dengan header permintaan HTTP, parameter permintaan API, nama elemen XML (seperti yang muncul dalam permintaan API), dan permintaan API yang tidak dibentuk dengan benar.

  • Bagian respons API menentukan panduan kompatibilitas mundur yang terkait dengan nama elemen XML (seperti yang muncul dalam respons API) dan urutan kemunculan tag dan atribut XML dalam respons API.

  • Bagian Praktik terbaik menguraikan rekomendasi untuk mengintegrasikan YouTube API dengan aplikasi klien Anda.

Permintaan API

Fungsi yang tidak dimaksudkan untuk berubah

  • Parameter permintaan yang ada.

  • Nilai parameter yang ada untuk parameter yang memiliki nilai yang dienumerasi atau arti nilai parameter tersebut.

  • Nama elemen XML yang digunakan dalam permintaan POST (sisipkan) atau PUT (perbarui) API.

  • Kumpulan header permintaan HTTP yang diperlukan untuk setiap jenis permintaan API. Panduan ini berarti bahwa YouTube tidak bermaksud menambahkan header permintaan HTTP yang diperlukan atau mengubah header permintaan opsional yang ada menjadi wajib.

  • Perilaku mengabaikan parameter yang tidak didukung dalam permintaan API kecuali jika permintaan menggunakan parameter strict, yang menginstruksikan YouTube untuk menolak permintaan API yang berisi parameter permintaan yang tidak valid.

Fungsi yang dapat berubah

  • YouTube dapat menambahkan parameter permintaan opsional.

  • YouTube dapat menambahkan nilai baru untuk parameter yang ada yang memiliki kumpulan nilai yang dihitung.

  • YouTube dapat menolak permintaan apa pun yang parameter validnya berisi nilai parameter yang tidak valid. Akibatnya, permintaan yang dibentuk dengan tidak benar yang telah diterima karena penguraian yang terlalu longgar dapat ditolak jika logika penguraian diperbaiki.

  • YouTube dapat menambahkan header permintaan HTTP opsional.

  • YouTube dapat mengubah informasi yang disimpannya saat menyisipkan atau memperbarui resource. Namun, keputusan tersebut tidak akan memengaruhi atau memerlukan perubahan pada sintaksis permintaan API yang sesuai.

  • YouTube dapat mengubah kumpulan kategori yang dapat dijelajahi atau kumpulan kategori yang dapat ditetapkan untuk video yang baru diupload.

  • Fungsi yang tidak didokumentasikan dapat dihapus atau diubah kapan saja.

Respons API

Fungsi yang tidak dimaksudkan untuk berubah

  • Nama tag XML yang ada.

  • Mengikuti spesifikasi RSS Media untuk menentukan urutan elemen yang ditentukan dalam spesifikasi tersebut dan yang muncul beberapa kali dalam entri feed. Misalnya, jika entri berisi beberapa tag <media:thumbnail>, tag tersebut akan diurutkan berdasarkan tingkat kepentingan.

  • Nilai atribut term dari tag <category> yang mengidentifikasi jenis item yang dijelaskan dalam feed atau entri feed. Dalam tag <feed> atau <entry>, tag <id> menentukan resource unik yang diidentifikasi oleh entri, dan tag <category> mengidentifikasi jenis resource yang dijelaskan oleh entri. Untuk tag <category> ini, nilai atribut skema adalah http://schemas.google.com/g/2005#kind dan nilai atribut istilah menunjukkan apakah entri feed mendeskripsikan video, link playlist, langganan, kontak, atau jenis entitas lainnya.

Fungsi yang dapat berubah

  • YouTube dapat menambahkan tag XML baru ke respons API.

  • YouTube dapat menambahkan atribut baru ke tag XML yang ada.

  • Tag API yang ada dapat diulang dengan nilai yang berbeda. Misalnya, YouTube dapat menambahkan tag <media:restriction> baru dengan nilai type yang berbeda atau tag <media:credit> baru dengan scheme dan role yang berbeda.

  • Urutan tag dan atribut XML dalam respons API dapat berubah.

  • Tag turunan opsional dapat dihapus dari respons API.

  • Fungsi yang tidak didokumentasikan dapat dihapus atau diubah kapan saja.

Praktik terbaik

  • Gunakan nilai tag <id> untuk mengidentifikasi entri.

  • Gunakan link self untuk mengambil entri.

  • Gunakan link edit untuk mengedit atau memperbarui entri.

  • Gunakan nilai tag <yt:videoid> untuk entri video guna mendapatkan nilai yang digunakan YouTube untuk mengidentifikasi video tersebut secara unik. Jangan mengurai ID video dari link.

  • Gunakan URL yang diidentifikasi dalam tag <link>, <content>, dan <gd:feedLink> untuk berpindah antar-feed. YouTube mendukung serangkaian URL terbatas yang dapat Anda buat dengan andal untuk mengambil feed tertentu. Selain URL feed tersebut, yang tercantum di bawah, Anda tidak boleh membuat URL feed sendiri karena URL tersebut dapat berhenti berfungsi secara tiba-tiba.

    • /feeds/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (lihat panduan referensi untuk informasi selengkapnya)

  • Jangan mencoba mengurai ID numerik atau alfanumerik dari URL dalam respons API. Respons API menyertakan tag tertentu untuk ID yang ditautkan ke resource di situs YouTube, seperti ID video (<yt:videoid>) dan nama pengguna (<name> dan <media:credit>).

  • Jika Anda mengirimkan permintaan API untuk menyisipkan (POST) atau memperbarui (PUT) informasi, gunakan respons XML untuk permintaan tersebut guna menentukan nilai tag dalam permintaan yang benar-benar disimpan oleh YouTube. Seperti yang disebutkan dalam panduan kompatibilitas mundur untuk permintaan API, YouTube dapat mengubah informasi yang disimpannya saat menyisipkan atau memperbarui resource, yang berarti beberapa tag dalam permintaan dapat diabaikan.

  • Saat Anda mengambil feed XML, simpan tag dan atribut XML yang tidak dikenal yang terkait dengan entri feed jika aplikasi Anda memungkinkan pengguna memperbarui entri tersebut. Jika pengguna memperbarui resource, aplikasi Anda harus menyertakan tag dan atribut yang tidak dikenal dalam permintaan pembaruan. Praktik ini memastikan bahwa aplikasi Anda tidak secara tidak sengaja menghapus informasi yang terkait dengan fitur API baru dalam proses memperbarui resource.

    Contoh berikut mengilustrasikan praktik terbaik ini:

    1. Aplikasi Anda memungkinkan pengguna memperbarui deskripsi video.
    2. Aplikasi Anda mengambil entri video menggunakan API, tetapi tidak mengenali salah satu tag dalam entri.
    3. Pengguna mengubah deskripsi video.
    4. Aplikasi Anda harus mengirim entri video lengkap kembali ke API. Entri harus menyertakan tag yang tidak dikenal dari langkah 2; jika tidak, nilai tersebut dapat dihapus.

  • Pastikan tag ada dan berisi nilai non-null sebelum mencoba menampilkan nilai tag.

  • Seperti yang disebutkan di atas, YouTube dapat menambahkan nilai baru untuk tag atau atribut yang ada yang memiliki kumpulan nilai yang dihitung. Sebagai aturan, kode Anda harus mengurai nilai elemen XML yang memiliki kumpulan nilai yang dihitung, lalu menentukan tindakan yang sesuai dengan nilai tersebut. Praktik ini direkomendasikan meskipun hanya satu kemungkinan nilai yang dihitung untuk elemen.

    Misalnya, tag <media:credit> mengidentifikasi pemilik video. Satu-satunya nilai yang didokumentasikan untuk atribut role tag adalah uploader, yang menunjukkan bahwa video diupload oleh partner YouTube. Praktik terbaik ini menetapkan bahwa aplikasi Anda harus mengonfirmasi bahwa nilai atribut role tag memang uploader sebelum mengidentifikasi pengguna yang sesuai sebagai pemilik video. (Tindakan pencegahan ini memastikan bahwa kode Anda tidak mengidentifikasi pemilik video secara tidak akurat jika YouTube menambahkan jenis kredit lain – misalnya, sutradara – untuk sebuah video.)

    • Jika tag memiliki kumpulan nilai yang disebutkan dan Anda tidak mengenali nilai tag tersebut, Anda harus mengabaikan seluruh <entry> tempat tag tersebut muncul.

    • Abaikan entri feed subscription jika Anda tidak mengenali nilai atribut term untuk tag <category> yang memiliki nilai atribut scheme http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Tag tertentu tersebut mengidentifikasi jenis langganan yang diidentifikasi oleh entri. Jika tidak mengenali jenis langganan, aplikasi Anda tidak akan menampilkan informasi tentang entri tersebut.

    • Jika atribut lain memiliki kumpulan nilai yang dihitung dan Anda tidak mengenali nilai atribut tersebut, Anda harus mengabaikan tag tempat atribut muncul.

  • Kode aplikasi Anda akan menerima pesan yt:error kapan saja. Jika operasi API gagal, aplikasi Anda harus mengidentifikasi error dan menampilkan pesan yang bermakna kepada pengguna.

  • YouTube dapat menambahkan kategori baru untuk mengklasifikasikan video kapan saja. YouTube juga dapat memperbarui atau menghentikan penggunaan kategori yang ada. Anda dapat mengambil file kategori saat ini dari http://gdata.youtube.com/schemas/2007/categories.cat.

    • Jika aplikasi Anda memungkinkan pengguna menjelajahi video menurut kategori atau mengupload video, ambil file kategori yang diperbarui setiap minggu.

    • Jika aplikasi Anda memungkinkan pengguna menjelajahi video berdasarkan kategori, ambil juga file kategori yang diperbarui jika API menampilkan feed kosong sebagai respons terhadap penelusuran kategori.

    • Jika aplikasi Anda memungkinkan pengguna mengupload video, ambil juga file kategori yang diperbarui sebelum mengupload video dan konfirmasi bahwa kategori yang terkait dengan video yang diupload masih dapat ditetapkan. Lihat panduan referensi untuk informasi selengkapnya. (Perhatikan bahwa jika Anda mencoba menetapkan video ke kategori yang tidak dapat ditetapkan, API akan menampilkan pesan error dengan nilai tag <code> adalah deprecated.)

  • Gunakan tag <link> dalam respons API untuk mengidentifikasi link penomoran halaman untuk halaman entri sebelumnya dan/atau berikutnya dalam feed. Lihat bagian Melakukan paging melalui hasil dalam panduan referensi untuk mengetahui informasi selengkapnya.