Memahami REST API - Panduan untuk Mereka yang Tidak Sabar

Crosspost artikel saya di sini

API

REST (Repersembahan State Transfer) ialah tulang belakang pembangunan web moden. Artikel ini akan menghuraikan cara untuk mencipta dan menggunakan API REST moden, keputusan reka bentuk yang perlu diambil kira semasa membuat satu, dan teori yang menjadi asas REST.

Panduan Praktikal

Bahagian ini menyelami penggunaan API REST dengan HTTP yang meliputi titik akhir, kaedah, permintaan dan respons. Anda akan menemui semua yang anda perlukan untuk mula membuat panggilan API dan menggunakan REST dalam projek anda.

Cara Menstrukturkan URI Anda

Secara amnya terdapat dua cara utama anda boleh merawat URI:

1. Sebagai tindakan
2. Sebagai sumber

Pertimbangkan dua URI berikut:

1. https://example.com/getUserData?id=1 (tindakan)
2. https://example.com/users/1 (sumber)

Kedua-dua contoh menunjukkan kami mendapatkan semula data pengguna pengguna dengan id 1. Perbezaannya ialah dalam contoh pertama laluan /getUserData sedang melakukan tindakan manakala dalam contoh kedua laluan /users/1 ialah lokasi sesuatu aset, ia tidak menunjukkan tindakan yang sedang dilakukan. Kita boleh mengatakan bahawa jenis URI ini bertindak sebagai kata nama (kerana ia adalah benda dan bukannya tindakan iaitu kata kerja).

Corak REST menetapkan bahawa kami menggunakan URI dengan ketat seperti contoh kedua. Kami mahu URI kami menjadi kata nama supaya kami boleh menggunakan Kaedah HTTP sebagai kata kerja kami untuk melakukan tindakan ke atas kata nama tersebut. Sebagai contoh, kami boleh menggunakan kaedah HTTP GET untuk mendapatkan maklumat tentang /users/1, tetapi kami boleh menggunakan PUT untuk mengemas kini maklumat pengguna yang sepadan itu, atau DELETE untuk memadamkan pengguna sepenuhnya.

Perkara terakhir yang perlu diambil perhatian tentang URI ialah, seperti contoh di atas, apabila merujuk sumber individu (mis. pengguna tunggal dalam kes ini) URI harus berakhir dengan pengecam unik untuk sumber tersebut. Apabila merujuk semua sumber dalam kategori tertentu, pengecam unik harus ditinggalkan.

1. https://example.com/users/1 - Merujuk pengguna tertentu dengan id 1
2. https://example.com/users - Merujuk kepada semua pengguna tanpa mengira id

Apakah Tindakan untuk Menyokong

Terdapat 4 tindakan utama untuk disokong dalam REST, kami menggunakan akronim CRUD untuk mengingatinya: Create, Read, U pdate, Delete. Setiap tindakan ini memetakan kepada Kaedah HTTP yang boleh kami gunakan untuk melaksanakan tindakan tersebut. Pemetaan adalah seperti berikut:

Action	HTTP Method
Create	POST
Read	GET
Update	PUT / PATCH
Delete	DELETE

Semua Gabungan URI Tindakan untuk Menyokong

Setiap API REST sebenarnya hanya (sekurang-kurangnya) 5-6 laluan. Dalam contoh kami, titik akhir asas ialah /users dan kami akan berpura-pura untuk mengehoskannya di https://example.com.

• DAPATKAN https://example.com/users
  • Tindakan: Kembalikan semua aset pengguna (setiap aset ialah seorang pengguna)
  • Minta Badan: Kosong
  • Badan Respons: Senarai aset pengguna (sebagai tatasusunan JSON)
• DAPATKAN https://example.com/users/[id] ([id] ialah pembolehubah)
  • Tindakan: Mengembalikan hanya aset pengguna tunggal yang diminta
  • Minta Badan: Kosong
  • Badan Respons: Hanya aset pengguna dengan id yang sepadan (sebagai JSON)
• SIARAN https://example.com/users
  • Tindakan: Menambahkan satu aset pengguna pada koleksi
  • Badan Permintaan: Semua data yang diperlukan untuk mencipta aset pengguna baharu (tiada format khusus diperlukan, JSON disyorkan)
  • Badan Respons: Aset yang baru dibuat yang telah dimasukkan ID unik (sebagai JSON)
• LETAKKAN https://example.com/users/[id] ([id] ialah pembolehubah)
  • Tindakan: Menggantikan sepenuhnya hanya satu data pengguna sedia ada dengan data yang diberikan
  • Isi Permintaan: Semua data yang diperlukan untuk menggantikan data pengguna sedia ada, sama ada ia telah berubah atau tidak (tolak id - tiada format khusus diperlukan, JSON disyorkan)
  • Badan Respons: Aset yang baru dikemas kini dengan id yang sepadan (sebagai JSON)
• (Pilihan) PATCH https://example.com/users/[id] ([id] ialah pembolehubah)
  • Tindakan: Menggantikan sebahagiannya hanya satu data pengguna sedia ada dengan data yang diberikan
  • Isi Permintaan: Hanya data yang perlu dikemas kini (tolak id - tiada format khusus diperlukan, JSON disyorkan)
  • Badan Respons: Aset yang baru dikemas kini dengan id yang sepadan (sebagai JSON)
• PADAM https://example.com/users/[id] ([id] ialah pembolehubah)
  • Tindakan: Memadamkan hanya satu rekod daripada jadual pengguna
  • Permintaan Badan: Tiada
  • Badan Respons: Tiada (hanya kod respons HTTP) ATAU Data daripada aset yang baru dipadamkan dengan id yang sepadan (sebagai JSON)

Pertimbangan Reka Bentuk

Di luar perkara yang mentakrifkan titik akhir sebagai menggunakan corak REST atau tidak, terdapat banyak perkara yang perlu diambil kira sebelum anda mula membina satu. Adakah terdapat kemungkinan anda ingin mengemas kini titik akhir anda pada masa hadapan? Sekiranya output anda memberikan petunjuk berguna kepada pengguna? Adakah REST adalah corak yang betul untuk digunakan dalam situasi anda? Mari jawab beberapa soalan ini.

Memversikan Titik Akhir Anda

Mungkin idea yang baik untuk mula memikirkan versi API anda dari awal supaya membuat perubahan lebih mudah pada masa hadapan. Terdapat beberapa kaedah berbeza untuk menentukan versi API yang pengguna anda pilih untuk digunakan:

• Penukaran URI
  • Nombor versi digabungkan ke dalam laluan URL, biasanya di pangkalan
  • Contoh:
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• Parameter Pertanyaan
  • Nombor versi dilampirkan sebagai parameter pertanyaan dalam titik akhir API
  • Contoh:
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• Berasaskan pengepala
  • Nombor versi ialah medan pengepala khusus dan unik
  • Contoh (Tajuk Permintaan):
  • versi-x-api: 1
  • versi-x-api: 2
• Perundingan Kandungan
  • Versi ditentukan berdasarkan keadaan perwakilan atau jenis media.
  • Dalam contoh di bawah, kod pelayan akan mengetahui bahawa firstName adalah untuk versi pertama dan bahawa ia telah ditukar kepada givenName dalam versi seterusnya.
  • Contoh (Badan Permintaan):
  • { firstNama: 'Henry' }
  • { diberiNama: 'Henry' }

Mengejek API REST Pantas

Kadangkala bermain-main dengan satu adalah alat terbaik untuk mempelajari cara ia berfungsi. Salah satu perpustakaan kegemaran saya untuk demo REST ialah json-server. Menyediakannya agak mudah - hanya beberapa langkah diperlukan.

Pasang Pelayan JSON

npm install json-server

Buat stor data ringkas

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

Mulakan pelayan

npx json-server db.json

Buat permintaan HTTP terhadap pelayan setempat anda

curl -X GET http://localhost:3000/users/1

Grid Data CRUD yang Mudah

Titik akhir REST yang berfungsi sepenuhnya boleh disambungkan ke grid data dengan mudah dengan ZingGrid, cuma halakan URI REST asas di atribut src elemen seperti di bawah

<zing-grid
  src="http://localhost:3000/users"
  editor-controls
></zing-grid>

Fikiran Akhir

API REST datang dalam pelbagai bentuk dan saiz di seluruh web, setiap satu disesuaikan untuk memenuhi keperluan tertentu. Dengan menstrukturkan URI dengan teliti, memilih tindakan yang betul dan mengingati versi, anda boleh mencipta API yang mudah dan fleksibel yang pembangun akan rasa senang untuk bekerja dengannya. Dengan langkah asas ini, walaupun prototaip pantas boleh berkembang menjadi API yang teguh dan boleh dipercayai yang tahan ujian masa.

Atas ialah kandungan terperinci Memahami REST API - Panduan untuk Mereka yang Tidak Sabar. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!