Pedoman Kompatibilitas Mundur

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

  • YouTube dapat merilis update ke versi API tertentu yang nomor versi barunya tidak ditetapkan untuk rilis tersebut. Update yang kompatibel dengan versi sebelumnya dapat menyertakan fitur API opsional, perbaikan bug, atau keduanya.

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

Dokumen ini menentukan pedoman kompatibilitas mundur untuk update pada versi API tertentu, item pertama yang tercantum di atas. Panduan ini berupaya membedakan berbagai 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 merusak. Misalnya, jika YouTube menambahkan tag XML baru ke respons API, kode Anda harus mengabaikan tag tersebut.

  • Pedoman ini juga mendefinisikan fungsi API yang tidak ingin diubah oleh YouTube saat mengupdate versi API tertentu. Dengan kata lain, Anda hanya perlu memperkirakan bahwa fungsi tersebut akan berubah jika YouTube merilis versi API baru, dan kode Anda tidak perlu berupaya untuk menangani jenis perubahan ini.

Tentang dokumen ini

Dokumen ini berisi bagian-bagian berikut:

  • Bagian Permintaan API menentukan pedoman 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 diformat dengan benar.

  • Bagian respons API akan menentukan panduan kompatibilitas mundur yang terkait dengan nama elemen XML (seperti yang muncul dalam respons API) dan urutan tag XML serta atribut yang muncul 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 enumerasi atau arti nilai parameter tersebut.

  • Nama elemen XML yang digunakan dalam permintaan API POST (masukkan) atau PUT (update).

  • Kumpulan header permintaan HTTP yang diperlukan untuk setiap jenis permintaan API. Dengan demikian, YouTube tidak akan menambahkan header permintaan HTTP yang diperlukan atau mengubah header permintaan opsional yang sudah ada menjadi wajib.

  • Perilaku mengabaikan parameter yang tidak didukung dalam permintaan API kecuali jika permintaan tersebut 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 terenumerasi.

  • YouTube dapat menolak permintaan apa pun yang berisi parameter valid yang berisi nilai parameter yang tidak valid. Akibatnya, permintaan dengan format yang salah yang telah diterima karena penguraian yang terlalu longgar dapat ditolak jika logika penguraian dikoreksi.

  • YouTube dapat menambahkan header permintaan HTTP opsional.

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

  • YouTube dapat mengubah serangkaian kategori yang dapat dijelajahi atau kumpulan kategori tempat video yang baru diupload diupload.

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

Respons API

Fungsi yang tidak dimaksudkan untuk berubah

  • Nama tag XML yang ada.

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

  • 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, subscription, 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 terdokumentasi 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 di antara feed. YouTube mendukung serangkaian URL terbatas yang dapat Anda buat dengan andal untuk mengambil feed tertentu. Selain URL feed tersebut, yang tercantum di bawah ini, Anda tidak boleh membuat URL feed Anda sendiri karena URL tersebut dapat berhenti berfungsi secara tidak terduga.

    • /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 identitas numerik atau alfanumerik dari URL dalam respons API. Respons API mencakup tag spesifik untuk ID yang tertaut 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 informasi (PUT), gunakan respons XML terhadap permintaan tersebut untuk menentukan nilai tag mana dalam permintaan yang benar-benar disimpan oleh YouTube. Seperti yang disebutkan dalam panduan kompatibilitas mundur untuk permintaan API, YouTube dapat mengubah informasi yang disimpan (menyimpan) saat menyisipkan atau memperbarui resource, yang berarti bahwa beberapa tag dalam permintaan mungkin 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 update. Praktik ini memastikan aplikasi Anda tidak menghapus informasi terkait fitur API baru secara tidak sengaja dalam proses update resource.

    Contoh berikut menggambarkan 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 tersebut.
    3. Pengguna mengubah deskripsi video.
    4. Aplikasi Anda perlu mengirim entri video lengkap kembali ke API. Entri harus menyertakan tag yang tidak dikenal dari langkah 2; jika tidak, nilai tersebut mungkin akan dihapus.

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

  • Seperti yang disebutkan di atas, YouTube dapat menambahkan nilai baru untuk tag atau atribut yang ada yang berisi kumpulan nilai yang disebutkan. Sebagai aturan, kode Anda harus mengurai nilai elemen XML yang telah menghitung kumpulan nilai, lalu menentukan tindakan yang sesuai dengan nilai tersebut. Praktik ini direkomendasikan meskipun hanya satu nilai yang memungkinkan yang disebutkan 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 dari 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 video.)

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

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

    • Jika ada atribut lain yang memiliki rangkaian nilai terenumerasi dan Anda tidak mengenali nilai atribut tersebut, sebaiknya abaikan tag tempat atribut ditampilkan.

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

  • YouTube dapat menambahkan kategori baru untuk mengklasifikasikan video kapan saja. YouTube juga dapat memperbarui atau menghentikan 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 menurut kategori, ambil juga file kategori yang diperbarui jika API mengembalikan feed kosong sebagai respons terhadap penelusuran kategori.

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

  • Gunakan tag <link> dalam respons API untuk mengidentifikasi link penomoran halaman untuk halaman entri sebelumnya dan/atau berikutnya dalam feed. Lihat bagian Paging by results di panduan referensi untuk informasi selengkapnya.