Panduan praktis tentang komponen REST API di folder wp-includes, cara membuat endpoint kustom, mekanisme izin, serta langkah debugging umum untuk memastikan rute REST berfungsi dengan baik.
Folder atau path yang berkaitan dengan REST API di instalasi WordPress berisi logika inti yang memungkinkan aplikasi berinteraksi lewat HTTP. Artikel ini menjelaskan konsep dasar, cara membuat endpoint kustom, mekanisme autentikasi/izin, serta tips troubleshooting yang sering diperlukan saat rute REST tidak merespons seperti diharapkan.
Panduan ditujukan untuk pengembang dan administrator situs yang ingin memahami atau menambah fungsionalitas berbasis REST API pada instalasi WordPress.
REST API adalah antarmuka yang memungkinkan pertukaran data menggunakan permintaan HTTP standar (GET, POST, PUT, DELETE). Di WordPress, REST API menyediakan cara untuk mengambil atau mengubah konten seperti post, halaman, user, dan tipe konten kustom melalui rute (endpoints) yang dapat diakses dari aplikasi lain.
API ini menggunakan format JSON untuk pertukaran data dan ditata dalam namespace serta rute yang ditentukan. Komponen inti di instalasi WordPress menangani pendaftaran rute, kontroler, validasi data, serta pemeriksaan izin.
Namespace dan rute: Setiap kumpulan endpoint biasanya ditempatkan dalam namespace tertentu, misalnya 'wp/v2' untuk endpoint bawaan. Rute mengikat pola URL ke callback yang menangani permintaan.
Callback dan permission_callback: Saat mendaftarkan rute, Anda menentukan fungsi callback untuk merespons permintaan, dan permission_callback untuk menentukan apakah pemanggil memiliki hak akses.
Schema dan validasi: Endpoint yang baik menyertakan definisi schema untuk struktur data yang diharapkan, serta pemeriksaan validasi untuk input yang masuk.
Controller dan objek respons: Untuk logika yang lebih terstruktur, WordPress menyediakan kelas dasar yang dapat di-extend untuk membuat controller, serta fungsi pembungkus untuk membentuk respons JSON beserta kode status HTTP.
Langkah dasar berikut menunjukkan pola umum pendaftaran rute kustom. Letakkan kode ini di plugin atau file functions.php tema anak jika diperlukan.
Contoh singkat pendaftaran rute:
add_action('rest_api_init', function () { register_rest_route('myplugin/v1', '/hello', array( 'methods' => 'GET', 'callback' => 'myplugin_hello_handler', 'permission_callback' => '__return_true', )); }); function myplugin_hello_handler($request) { return rest_ensure_response(array('message' => 'Halo dari endpoint kustom')); }
Penjelasan singkat: gunakan rest_api_init untuk mendaftarkan rute saat inisialisasi API. register_rest_route menerima namespace, pola rute, dan konfigurasi seperti methods, callback, dan permission_callback. Gunakan permission_callback untuk membatasi akses sesuai kebutuhan.
Tipe autentikasi umum yang dipakai pada WordPress meliputi autentikasi berbasis cookie (untuk permintaan dari browser yang sudah login), serta metode berbasis token atau kredensial untuk aplikasi eksternal. Pada level rute, permission_callback bertanggung jawab memastikan pemanggil diizinkan melakukan aksi tertentu.
Saat membuat endpoint yang memodifikasi data, jangan menetapkan permission_callback yang selalu mengembalikan true. Gunakan pemeriksaan kemampuan (capabilities) seperti current_user_can('edit_posts') atau validasi terhadap credential sebelum mengizinkan tindakan sensitif.
Untuk integrasi aplikasi pihak ketiga, pertimbangkan mekanisme autentikasi yang sesuai dengan kebutuhan, dan pastikan komunikasi berlangsung melalui HTTPS.
Jika sebuah rute tidak merespons atau menghasilkan kesalahan, langkah-langkah pemeriksaan berikut sering membantu:
1) Pastikan permalinks di situs telah diatur sehingga rewrite rules aktif. Perubahan struktur permalink kadang memerlukan penyegaran rewrite rules.
2) Periksa apakah hook rest_api_init dipanggil pada waktu yang tepat (biasanya saat inisialisasi). Pendaftaran rute yang dilakukan terlalu awal atau terlambat dapat menyebabkan rute tidak tersedia.
3) Cek konflik namespace atau rute dengan plugin/tema lain. Sama seperti URL lain di situs, rute REST dapat bentrok jika dua penyedia mendaftarkan pola yang sama.
4) Verifikasi permission_callback dan pemeriksaan kemampuan; sering kali rute tampak seperti 'hilang' karena callback izin menolak akses.
5) Gunakan alat pengujian seperti curl atau aplikasi API client (Postman, HTTPie) untuk melihat respons mentah, header, dan kode status HTTP. Header respon dapat memberi petunjuk masalah seperti kode 404, 401, atau 500.
6) Lihat log error server dan log PHP untuk menemukan fatal error atau peringatan yang menghentikan eksekusi.
7) Sebagai langkah terakhir, nonaktifkan sementara plugin yang berpotensi konflik atau beralih tema ke tema default untuk mengisolasi sumber masalah.
Beri namespace dan pola rute yang jelas dan unik agar tidak bertabrakan dengan rute lain. Dokumentasikan setiap endpoint, parameter yang diterima, dan jenis respons yang dikembalikan.
Selalu validasi dan sanitasi input; jangan percaya data yang dikirim oleh klien. Gunakan fungsi sanitasi dan validasi bawaan untuk memastikan integritas data.
Kembalikan kode status HTTP yang sesuai untuk setiap respons (200 untuk sukses, 201 untuk pembuatan, 400 untuk input tidak valid, 401/403 untuk masalah izin, 404 jika sumber tidak ditemukan, 500 untuk kesalahan server internal).
Pertimbangkan pembatasan laju (rate limiting) dan caching jika endpoint dipanggil sering oleh aplikasi eksternal untuk mengurangi beban server.