WP REST API: Mengambil Data

Indonesian (Bahasa Indonesia) translation by Hasannudin Amin (you can also view the original English article)

Di bagian sebelumnya dari seri, kita telah melihat apa itu WP REST API dan bagaimana hal itu dapat membantu kita membangun aplikasi yang lebih baik menggunakan back end WordPress.

Kemudian kita melihat dua cara untuk mengatur otentikasi pada server untuk menghasilkan permintaan dikonfirmasi. Yang pertama adalah metode otentikasi dasar, yang berguna dalam lingkungan pengembangan dan memungkinkan pembuatan prototipe yang cepat karena tidak memerlukan banyak waktu untuk menyiapkannya. Metode otentikasi kedua adalah OAuth 1.0a, yang direkomendasikan untuk lingkungan produksi karena jauh lebih aman daripada metode otentikasi dasar.

Sekarang kita telah belajar cara mengatur otentikasi, kita siap untuk menghasilkan permintaan dikonfirmasi untuk melepaskan kekuatan penuh dari WP REST API. Kita akan menggunakan otentikasi dasar di seluruh seri ini karena kemudahan penggunaannya, tetapi sebaiknya Anda menggunakan autentikasi OAuth 1.0a, seperti yang disediakan oleh plugin OAuth 1.0a, untuk server produksi Anda.

Di bagian seri saat ini, kita akan mendapatkan pengalaman langsung pertama kita dengan plugin WP REST API. Kita akan:

menganalisis struktur permintaan GET
melihat bagaimana OPTIONS meminta dokumen sendiri pada API
mengirim permintaan ke server untuk pengambilan data
menganalisis respons server yang menyertakan properti, skema, dan tautan

Jadi mari kita mulai dengan menganalisis struktur permintaan GET yang sederhana.

Anatomi Permintaan `GET`

Sebelum kita menyelidiki detail pengambilan data apa pun dengan WP REST API, kita harus membiasakan diri dengan sintaks permintaan yang dikirimkan ke server. Ini akan meletakkan dasar yang kuat untuk interaksi masa depan kita dengan WP REST API.

Pertimbangkan permintaan berikut yang dikirim ke server:

1	$ GET https://localserver/wp-json/wp/v2/posts

Jenis permintaan yang kita kirimkan adalah GET — salah satu dari enam kata kerja HTTP yang kita lihat di bagian awal dari seri ini. Permintaan GET digunakan untuk mengambil data dari server. Oleh karena itu, ketika dieksekusi di server, permintaan di atas mengambil koleksi semua objek pos dalam bentuk data JSON.

Mempertimbangkan permintaan URI, kita dapat memecahnya menjadi bagian-bagian berikut:

http://localserver/: URL server pengembangan lokal saya. Bisa jadi URL apa pun tergantung di mana instalasi WordPress Anda berada.
/wp-json: Ini adalah awalan titik akhir dari WP REST API.
/wp: Namespace dari plugin WP REST API.
/v2: Ini adalah versi dari plugin WP REST API.
/posts: Ini adalah sumber daya yang ingin kita ambil dari server.

Namespace mencegah penimpaan yang mungkin terjadi saat menjalankan beberapa plugin dengan masing-masing menyediakan lapisan abstraksinya sendiri untuk RESTful API. Oleh karena itu, setiap abstraksi bekerja di batasnya sendiri tanpa mempengaruhi metode dan properti yang termasuk beberapa abstraksi lainnya.

Namespace dan versi tidak ada di versi lawas 1.2 dari plugin. Jadi dalam versi lama, permintaan di atas akan seperti ini:

1	$ GET http://localserver/wp-json/posts

Namun kita tidak akan berbicara tentang kompatibilitas ke belakang di sini. Jika Anda ingin mempelajari semua perubahan yang terjadi antara versi 1.x dan 2.x, Anda dapat menemukannya di halaman resmi.

Selain mengambil koleksi sumber daya (posting) menggunakan URI di atas, kita juga dapat mengambil sumber daya tertentu dengan menyebutkan ID-nya:

1	$ GET /wp/v2/posts/100

Permintaan di atas akan mengembalikan objek pos karena melihat ke bawah untuk sumber daya posting yang memiliki ID 100.

Di lain waktu, kita juga perlu mencari posting yang memenuhi beberapa kriteria tertentu. Untuk tujuan itu, WP REST API menyediakan cara menggunakan sintaks filter[]:

1	$ GET /wp/v2/posts?filter[cat]=1

Dengan mengirim permintaan di atas, kita dapat mengambil semua pos milik kategori ID 1. Sintaks filter dapat sangat membantu ketika menanyakan posting atau menavigasi antara sumber daya yang berbeda, misal posting dan kategori, menggunakan hubungan mereka.

Akhirnya, ketika berhadapan dengan argumen yang mengambil array sebagai input dalam sintaks filter[], kita dapat menambahkan seperangkat kurung kotak kosong untuk mengekspresikan array seperti ini:

1	$ GET /wp/v2/posts?filter[category__and][]=1&filter[category__and][]=2

Sintaks di atas setara dengan WP_Query() berikut:

<?php

$query = new WP_Query( array(
    'category__in'  => array( 1, 2 )
) );

Oleh karena itu, permintaan GET di atas akan mengambil daftar posting yang termasuk dalam kedua kategori yang memiliki ID 1 dan 2. Sintaks yang sama juga dapat digunakan untuk argumen array yang memiliki lebih dari dua elemen. Harap perhatikan bahwa penggunaan parameter category__and memerlukan autentikasi pengguna dengan hak istimewa edit_posts.

Kita akan melihat sintaks filter[] secara lebih rinci di bagian selanjutnya.

Sekarang setelah kita belajar tentang memformat permintaan GET dan memberikan parameternya, sekarang saatnya untuk melihat permintaan OPTIONS. Permintaan OPTIONS memudahkan menavigasi melalui API dan benar-benar berfungsi sebagai cara mendokumentasikan diri untuk membuat API lebih mudah diakses dengan mendokumentasikan semua metode HTTP yang tersedia pada titik akhir, dan pada gilirannya, argumen yang mereka dukung.

Menavigasi Melalui API Menggunakan Permintaan `OPTIONS`

Seperti yang disebutkan sebelumnya, permintaan OPTIONS dapat sangat membantu dalam menjelajahi API. Ini menyebutkan semua titik akhir yang termasuk ke rute tertentu dan memberikan daftar parameter dukungan titik akhir ini untuk operasi CRUD.

Mari kirim permintaan OPTIONS ke rute /wp/v2/posts untuk memeriksa titik akhir mana yang didukung dan parameter mana yang dapat kita berikan bersama permintaan GET ke data kueri:

1	$ curl -X OPTIONS wp/v2/posts

Saya telah menggunakan cURL untuk mengirim permintaan di atas, tetapi Anda dapat menggunakan alat apa pun pilihan Anda, termasuk Postman. Pastikan untuk menyertakan jalur lengkap ke rute di atas, termasuk jalur server Anda.

1	{
2	"namespace": "wp/v2",
3	"methods": [...],
4	"endpoints": [...],
5	"schema": {...},
6	"_links": {...}
7	}

Permintaan OPTIONS di atas ke rute /wp/v2/posts mengembalikan data dalam format JSON yang berisi lima properti:

namespace
methods
endpoints
schema
_links

1	{
2	"namespace": "wp/v2",
3	....
4	}

Properti namespace mengidentifikasi namespace dari plugin saat ini. Dalam kasus kami, wp/v2, menandakan versi 2 WP REST API. Kita telah melihat namespace dan tujuan yang dilayaninya di bagian sebelumnya.

1	{
2	...
3	"methods": [
4	"GET",
5	"POST"
6	],
7	...
8	}

Properti methods berisi larik semua metode yang didukung oleh rute saat ini. Dengan melihat respons, permintaan di atas kembali, jelas bahwa rute /wp/v2/posts mendukung dua metode, yaitu GET dan POST. Ini berarti bahwa kita dapat menggunakan rute /wp/v2/posts untuk mengambil posting, serta membuat posting baru. Kita akan membahas metode POST di bagian selanjutnya dari seri ini, jadi mari fokus saja pada metode GET untuk saat ini.

Properti berikutnya—endpoint—mengandung larik titik akhir yang didukung untuk rute saat ini. Properti ini secara langsung terkait dengan properti methods yang disebutkan sebelumnya karena daftar titik akhir untuk metode yang didukung.

1	{
2	...
3	"endpoints": [
4	{
5	"methods": [
6	"GET"
7	],
8	"args": {...}
9	},
10	{
11	"methods": [
12	"POST"
13	],
14	"args": {...}
15	}
16	],
17	...
18	}

Properti endpoints berisi nilai objek yang pada gilirannya berisi dua properti, yaitu methods dan args. Properti methods berisi array metode HTTP, dan properti args berikutnya berisi semua argumen yang didukung untuk metode ini. Ini adalah argumen yang kita kirimkan bersama permintaan dalam bentuk parameter URI.

Melihat argumen yang didukung oleh metode GET, kita menemukan sembilan argumen yang mencakup context, page, per_page, dll. Objek argumen ini mengandung dua properti, required dan default. Properti required menunjukkan apakah argumen diperlukan, dan properti default mewakili nilai default dari argumen.

"methods": [
        "GET"
    ],
"args": {
    "context": {
        "required": false,
        "default": "view"
    },
    "page": {
        "required": false,
        "default": 1
    },
    "per_page": {
        "required": false,
        "default": 10
    },
    "filter": {
        "required": false
    }
}

Properti schema dalam respons yang dikembalikan mendokumentasikan semua properti untuk sumber daya saat ini. Skema mendefinisikan struktur untuk data dalam format JSON. Format skema yang digunakan dalam WP REST API didasarkan pada draf 4 dari spesifikasi skema JSON.

Properti _link terakhir memegang larik objek yang berisi tautan sumber daya terkait. Kunci dalam objek menentukan jenis hubungan (misalnya author, collection, self, comments, dll.), Dengan nilainya sebagai tautan ke sumber daya terkait. Standar penautan ini didasarkan pada HAL (Hypertext Application Language). Anda dapat menemukan lebih banyak tentang HAL dengan membaca spesifikasi yang ditulis oleh Mike Kelley.

Dengan cara yang sama, kita dapat mengirim permintaan OPTIONS ke rute lain, termasuk pengguna, komentar, media, halaman, dll., Untuk memeriksa metode dan argumen yang didukung. Permintaan OPTIONS adalah teman terbaik Anda saat bekerja dengan WP REST API.

WP REST API menyediakan cara lain untuk menilai ketersediaan API dengan mengirimkan permintaan GET ke rute indeks /wp-json. Ini akan mencantumkan semua rute dan endpoints mereka bersama dengan metode dan argumen yang didukung.

1	$ curl -X GET http://wordpress-server/wp-json

Permintaan di atas akan mengembalikan objek respons berisi properti rute sebagai berikut:

Fitur ini sangat kuat karena mencantumkan semua rute dan metode dan argumen yang didukung, sehingga menghilangkan kebutuhan untuk semua ini untuk didokumentasikan secara eksternal. Kita akan mengacu pada objek respons ini ketika melakukan operasi CRUD pada sumber daya yang berbeda.

Setelah melihat opsi kita untuk menjelajahi API, mari mulai bekerja dengan WP REST API untuk mengambil data dari server.

Bekerja Dengan Post

Sekarang, kita telah membiasakan diri dengan permintaan OPTIONS, yang merupakan cara mendokumentasikan diri untuk menilai ketersediaan API. Kita juga melihat bagaimana itu menunjukkan metode dan argumen yang didukung untuk rute tertentu. Menggunakan pengetahuan ini, kita sekarang siap untuk mengambil sumber daya yang berbeda dari server menggunakan WP REST API.

Sumber daya yang akan kita mulai adalah sumber daya Post, karena itu adalah blok bangunan utama WordPress. Kita akan berurusan dengan mengambil posting menggunakan filter yang berbeda. Menerapkan pengetahuan ini, Anda akan dapat query posting menggunakan WP REST API seperti yang Anda lakukan dengan kelas WP_Query().

Sepanjang seri ini, kita telah bekerja dengan sumber daya Post untuk mendemonstrasikan contoh permintaan dan tanggapan mereka, dan kami sudah tahu cara mengambil koleksi pos dan posting individual berdasarkan ID-nya. Jadi kita tidak akan membahasnya lagi. Sebagai gantinya, kita akan melihat beberapa cara yang lebih maju untuk mengambil posting menggunakan parameter level teratas dan sintaks filter[].

Bekerja Dengan Parameter Tingkat Atas

WP REST API mengekspos beberapa variabel kueri yang paling sering digunakan untuk posting secara langsung di endpoint GET. Parameter ini adalah:

context: Ruang lingkup permintaan. Nilai yang mungkin adalah view, embed atau edit.
page: Halaman saat ini dari koleksi pos.
per_page: Jumlah total posting per halaman.
search: Kueri pencarian. Membatasi hasil ke string yang cocok.
author: ID penulis. Digunakan untuk membatasi hasil milik penulis tertentu.
exclude: Larik ID postingan untuk dikecualikan dari hasil pencarian.
include: Batasi hasil untuk memposting ID yang ditentukan dalam larik ini.
offset: Offset hasil pencarian dengan nomor yang ditentukan.
order: Urutan koleksi. Bisa berupa asc atau desc.
orderby: Menyortir atribut koleksi. Nilai yang mungkin bisa berupa id, title or slug.
slug: Batasi hasilnya ke pos yang memiliki slug khusus.
status: Digunakan untuk membatasi koleksi posting yang memiliki status tertentu.

Parameter context digunakan untuk mengambil tulisan tergantung pada cakupan tempat kita bekerja. Jika kami hanya mencantumkan posting di beberapa halaman indeks, maka kami baik untuk menggunakan konteks view. Tetapi jika kami mengambil posting untuk mengeditnya, maka kita perlu menggunakan konteks edit:

1	$ GET /wp/v2/posts?context=edit

Parameter konteks edit memperkenalkan bidang raw tambahan di bidang seperti title, context, excerpt dll. Nilai bidang raw ini dapat disuarakan di editor untuk mengedit konten.

Menggunakan konteks edit mengharuskan Anda untuk diautentikasi sebagai pengguna dengan hak istimewa edit_posts.

Menggunakan embed sebagai nilai parameter context mengambil koleksi posting dengan subset minimal dari propertinya.

Parameter lain yang disebutkan di atas cukup jelas, dan Anda dapat bermain-main dengan mereka di klien HTTP Anda.

Ini adalah parameter dasar yang memungkinkan Anda untuk kueri posting berdasarkan kriteria tertentu. Untuk mempersempit kemampuan query kita, WP REST API menyediakan sintaks filter[] yang mendukung subset dari argumen WP_Query().

Menggunakan sintaks `filter[]`

Selain mengambil koleksi posting menggunakan beberapa parameter tingkat dasar, WP REST API memaparkan beberapa variabel WP_Query() menggunakan sintaks filter[]. Dengan menggunakan sintaks ini, kita dapat melakukan kueri posting dengan cara yang sama seperti yang kita lakukan ketika bekerja dengan kelas WP_Query().

Parameter paginasi adalah yang paling penting dari semua filter, karena mereka digunakan secara luas pada halaman daftar posting. Parameter paginasi memungkinkan kami untuk menampilkan jumlah posting tertentu per halaman dan menavigasi ke sejumlah halaman tertentu yang berisi tulisan.

Secara default, permintaan GET mengambil koleksi 10 posting per halaman. Mari kita lihat bagaimana kita dapat mengajukan permintaan GET untuk mengambil hanya lima posting per halaman:

1	$ GET /wp/v2/posts?filter[posts_per_page]=5

Permintaan di atas menggunakan variabel posts_per_page yang mungkin Anda kenal jika Anda telah bekerja dengan WP_Query().

Parameter paged digunakan bersama dengan parameter posts_per_page, dan digunakan untuk menavigasi ke sejumlah halaman tertentu. Setelah mengambil lima posting per halaman, kita akan membuat permintaan berikut untuk menavigasi ke halaman kedua:

1	$ GET /wp/v2/posts?filter[posts_per_page]=5&filter[paged]=2

posts_per_page dan paged filter bisa sangat berguna ketika bekerja untuk membangun pagination pada halaman daftar menggunakan WP REST API. Kedua parameter ini setara dengan parameter tingkat atas per_page dan page. Oleh karena itu, permintaan berikut melakukan pekerjaan yang sama seperti yang di atas:

1	$ GET /wp/v2/posts?per_page=5&page=2

Selain koleksi posting di atas permintaan kembali, server juga mengembalikan sejumlah header dengan respon yang berisi informasi yang berguna, termasuk jumlah posting dan jumlah halaman. Nilai-nilai ini tercantum dalam header respons X-WP-TotalPages dan X-WP-Total.

Header respons X-WP-TotalPages dan X-WP-Total sangat berguna ketika membuat pagination menggunakan WP REST API karena mereka mencantumkan jumlah total halaman dan jumlah total posting masing-masing.

Selain dari filter paginasi, penggunaan sintaks filter[] yang paling penting lainnya adalah untuk dapat mengquini kiriman berdasarkan tanggalnya. Untuk tujuan ini, sintaks filter[] mendukung delapan parameter, sama dengan parameter kelas WP_Query():

year: Empat digit tahun (misalnya 2015 atau 2016)
monthnum: Jumlah bulan dari 1 hingga 12
m: Enam digit tahun bulan (misalnya, 201601)
w: Minggu dalam setahun dari 0 hingga 53
day: Hari dalam sebulan dari 1 hingga 31
hour: Jam dalam sehari dari 0 hingga 23
minute: menit dari jam mulai dari 0 hingga 60
second: Detik dari menit dari 0 hingga 60

Jadi jika kita mencari posting yang diterbitkan pada tanggal 2015-10-15 (yyyy/mm/dd), ini dapat dicapai dengan query berikut:

1	$ GET /wp/v2/posts?filter[year]=2015&filter[monthnum]=10&filter[day]=15

Permintaan serupa dapat disiapkan dengan bantuan parameter di atas jika kita perlu mempersempit pencarian kita ke jam dan menit yang tepat.

Kita telah melihat di bagian sebelumnya dari tutorial ini bagaimana kita bisa mengambil posting milik kategori tertentu atau beberapa kategori menggunakan filter[cat] dan filter[category__and] parameter. Sekarang kita akan menggunakan parameter filter [category__in] untuk menampilkan kiriman milik kategori yang memiliki id 5 dan 6:

1	$ GET /wp/v2/posts?filter[category__in][]=5&filter[category__in][]=6

Permintaan di atas akan mengambil daftar semua pos milik kategori yang memiliki id 5 dan 6.

Efek sebaliknya dapat dicapai dengan menggunakan filter[category__not_in] parameter dengan cara berikut:

1	$ GET /wp/v2/posts?filter[category__not_in][]=5&filter[category__not_in][]=6

Ini akan mengambil daftar postingan sementara mengecualikan semua kiriman milik kategori yang memiliki ID baik 5 atau 6.

Lebih lanjut dapat ditulis menggunakan sintaks filter[], tetapi saya tidak akan membahas semua itu di sini. Anda dapat menemukan daftar semua variabel kueri yang didukung oleh sintaks filter[] dalam dokumentasi resmi versi 1 dari plugin. Sebagian besar informasi ini masih berlaku dengan versi 2 WP REST API, tetapi masih kurang di beberapa area. Pada saat penulisan tutorial ini, dokumentasi resmi versi 2 tidak menyatakan apa pun tentang sintaks filter[] dan var query yang didukungnya, tetapi kita berharap dapat melihat perbaikan dalam dokumentasi resmi dalam waktu dekat karena ada sejumlah orang (termasuk saya) berkontribusi pada pengembangan dan dokumentasi plugin.

Sekarang kita telah melihat pilihan yang berbeda ketika query posting dengan bantuan WP REST API, kita siap untuk lebih memajukan perjalanan kita dan melihat beberapa sumber lain yang didukung oleh WP REST API.

Bekerja Dengan Posting Revisi, Kategori, Tag, dan Meta

Revisi pos menyediakan cara untuk melihat dan mengembalikan suntingan yang dibuat ke pos. WP REST API menyediakan cara untuk melihat semua revisi posting dengan query /post/<id>/revisions endpoint. Oleh karena itu untuk posting yang diberikan memiliki ID dari 10, semua revisi dapat diambil dengan mengirim permintaan berikut:

1	$ GET /wp/v2/posts/10/revisions

Permintaan di atas akan mengembalikan array yang berisi objek revisi. Objek revisi berisi sebagian properti yang ditemukan di objek pos. Di bawah ini adalah contoh objek revisi di Postman:

Revisi tertentu dapat diambil mengingat bahwa kita tahu idnya. Jadi revisi yang memiliki ID 2 dengan postingan yang memiliki ID 10 dapat diambil oleh objek berikut:

1	$ GET /wp/v2/posts/10/revisions/2

Permintaan di atas akan mengembalikan objek revisi tunggal.

Selain revisi pos, kategori untuk posting tertentu dapat diambil dengan permintaan berikut:

1	$ GET /wp/v2/categories?post=<post_id>

Dan untuk tag, kita menggunakan permintaan berikut:

1	$ GET /wp/v2/tags?post=<post_id>

Dengan <post_id> menjadi ID dari postingan.

Jika kita perlu mengambil pos meta untuk postingan yang memiliki ID 10, kita mengirim permintaan berikut sebagai pengguna yang diautentikasi:

1	$ GET /wp/v2/posts/10/meta

Ini akan mengembalikan array objek meta.

Harap dicatat bahwa untuk bekerja dengan meta posting dan halaman di WP REST API, Anda harus menginstal plugin pendamping yang tersedia di GitHub oleh tim WP REST API.

Bekerja dengan Sumber Daya Lain

Sekarang, kita telah mendapatkan landasan yang cukup kuat untuk bekerja dengan WP REST API untuk mengambil data. Kita telah melihat permintaan opsi dan bagaimana hal itu membantu kita menjelajahi API tanpa perlu dokumentasi eksternal.

Anda selalu dapat mengirim permintaan OPTIONS ke sumber daya tertentu dan memeriksa apa endpoint dan parameter yang didukungnya. Jika Anda perlu mendaftar semua rute yang disediakan oleh WP REST API, Anda dapat mengirim permintaan GET ke titik akhir indeks di /wp-json seperti yang telah kita pelajari di awal tutorial ini.

Dengan mempertimbangkan manfaat dokumentasi mandiri ini, saya tidak berpikir bahwa kita perlu menggali lebih jauh setiap sumber daya individual dalam tutorial ini, karena Anda sekarang dapat melakukannya sendiri.

Apa Selanjutnya?

Dalam tutorial yang panjang ini, kami belajar untuk mengeksplorasi API menggunakan permintaan OPTIONS serta mengambil data dari server menggunakan API REST WP. Kita baru saja melihat beberapa sumber daya termasuk postingan, postingan revisi, dan post meta, karena kita tidak dapat mencakup semua sumber daya yang didukung hanya dalam satu tutorial. Tetapi Anda sekarang dapat menjelajahi API sendiri menggunakan teknik yang kita pelajari di tutorial ini.

WordPress memiliki ekonomi yang sangat aktif. Ada tema, plugin, pustaka, dan banyak produk lain yang membantu Anda membangun situs dan proyek Anda. Sifat open source dari platform juga menjadikannya pilihan yang bagus dari mana Anda dapat lebih baik keterampilan pemrograman Anda. Apapun masalahnya, Anda dapat melihat apa yang kita miliki di Envato Marketplace.

Dalam rangkaian berikutnya dari seri ini, kita akan belajar untuk melakukan tiga operasi CRUD lainnya, yaitu membuat, memperbarui, dan menghapus sumber daya. Jadi nantikanlah...