Bagaimana informasi tentang Definisi API dapat diverifikasi?

Apa arti Definisi API dalam praktik

Definisi API biasanya merujuk pada spesifikasi formal tentang cara kerja sebuah API: endpoint (atau operasi) yang tersedia, input yang diperlukan, input opsional, output yang diharapkan, tipe data, aturan validasi, dan format kesalahan. Definisi ini dapat ditulis sebagai dokumen OpenAPI/Swagger, skema JSON, spesifikasi pengembang internal, atau dokumentasi yang dapat dibaca manusia.

Saat Anda memverifikasi informasi tentang Definisi API, Anda tidak mencoba mengonfirmasi bahwa sebuah ide “benar” secara umum—Anda memeriksa apakah kontrak yang didokumentasikan konsisten, dapat diuji, dan dapat direproduksi untuk versi API tertentu.

Bagaimana proses verifikasi bekerja (hierarki sumber)

Gunakan hierarki sumber yang sesuai dengan cara “mekanisme yang stabil” harus dikonfirmasi.

1. Artefak kontrak utama (paling stabil)

   • Dokumen definisi API aktual yang diterbitkan oleh penyedia (misalnya, file OpenAPI).
   • Skema yang dapat dibaca mesin yang disertakan dengan dokumentasi.
   • Pengidentifikasi versi yang didokumentasikan dan catatan perubahan.

2. Dokumentasi penyedia (lapisan interpretasi)

   • Panduan yang menjelaskan cara menyusun permintaan dan menafsirkan respons.
   • Bagian penanganan kesalahan dan autentikasi/otorisasi, jika memengaruhi struktur permintaan/respons.

3. Perilaku yang diamati dari pengujian terkontrol (pemeriksaan realitas)

   • Serangkaian kecil permintaan di lingkungan non-produksi atau sandbox jika tersedia.
   • Validasi bahwa bidang, tipe, dan batasan respons sesuai dengan definisi.

Dalam praktiknya, verifikasi paling kuat ketika Anda dapat menunjukkan bahwa dokumentasi, skema, dan respons sesuai untuk versi yang sama.

Bukti dan langkah verifikasi yang dapat direproduksi

Ikuti proses langkah demi langkah yang dapat Anda ulangi.

Langkah 1: Kunci versi dan ruang lingkup

Catat versi API dan artefak definisi persis yang Anda gunakan (nama file, URL, atau pengidentifikasi commit). Asumsikan bahwa versi yang berbeda mungkin memiliki nama bidang, parameter wajib, dan format kesalahan yang berbeda.

Langkah 2: Periksa silang struktur terhadap definisi

Untuk setiap endpoint yang Anda pedulikan, verifikasi bahwa:

• Daftar parameter wajib bersifat eksplisit.
• Parameter opsional dapat dibedakan.
• Bidang output didokumentasikan dengan tipe data atau skema.
• Respons kesalahan memiliki struktur yang didokumentasikan (misalnya, kode kesalahan plus pesan, atau daftar masalah validasi).

Langkah 3: Buat kasus uji minimal dengan asumsi eksplisit

Pilih serangkaian kecil permintaan yang mencakup:

• Kasus “jalur bahagia” dengan hanya bidang wajib.
• Kasus validasi (sengaja salah tipe atau menghilangkan bidang wajib) untuk mengonfirmasi perilaku kesalahan.

Asumsikan tidak ada data pasar real-time. Jika API memerlukan parameter yang biasanya bergantung pada keadaan eksternal (seperti simbol atau pengidentifikasi), gunakan nilai yang disediakan lingkungan pengujian Anda, atau perlakukan nilai yang hilang/tidak valid sebagai input pengujian daripada mencoba memprediksi hasil.

Langkah 4: Bandingkan respons dengan definisi

Untuk setiap respons:

• Periksa bahwa payload respons menyertakan bidang yang dijelaskan.
• Periksa bahwa tipe data sesuai dengan ekspektasi (string vs angka, objek vs daftar).
• Konfirmasi bahwa kesalahan dibentuk sesuai dokumentasi saat permintaan tidak valid.

Jika definisi menyatakan bahwa sebuah bidang bersifat opsional tetapi tidak pernah muncul dalam respons, itu adalah perbedaan yang perlu dicatat. Sebaliknya, jika bidang tambahan muncul secara konsisten, catat sebagai “diamati tetapi tidak didokumentasikan,” yang dapat menunjukkan kesenjangan dokumentasi.

Langkah 5: Lacak mode kegagalan, bukan hanya hasil

Setidaknya satu keterbatasan material harus menjadi bagian dari verifikasi:

• Pergeseran versi: dokumentasi mungkin tertinggal dari perilaku setelah pembaruan.
• Skema yang tidak konsisten: bidang mungkin didokumentasikan tetapi hilang atau diubah namanya.
• Perbedaan validasi: format kesalahan dapat berubah di seluruh endpoint.
• Perbedaan lingkungan: perilaku sandbox dan produksi mungkin tidak cocok.

Perlakukan ini sebagai hasil verifikasi, bukan sebagai sinyal kebenaran.

Keterbatasan dan risiko yang diharapkan

Bahkan dengan pemeriksaan yang cermat, verifikasi dibatasi oleh ketidakpastian dan perubahan.

• Tidak ada satu pengujian pun yang menjamin akurasi jangka panjang. Definisi bisa benar hari ini dan tetap menjadi usang setelah pembaruan penyedia.
• Perilaku dapat bervariasi berdasarkan konteks. Biaya, kondisi eksekusi, izin, dan kegagalan jaringan dapat mengubah respons yang Anda lihat, bahkan ketika kontrak stabil.
• Kesesuaian historis tidak menjamin kesesuaian di masa depan. Jika respons cocok sebelumnya, itu tidak menjamin kecocokan setelah perubahan versi.

Karena keterbatasan ini, pertahankan verifikasi terikat pada versi tertentu dan lingkungan pengujian tertentu.

Daftar periksa verifikasi dan pertanyaan berikutnya yang harus diselesaikan

Gunakan daftar periksa ini untuk membuat verifikasi Anda dapat direproduksi:

• Versi dicatat untuk dokumentasi dan pengujian. - Endpoint dan bidang dihitung dari definisi. - Permintaan “jalur bahagia” dan “kegagalan validasi” minimal dibuat dengan asumsi eksplisit.