REST dan Semantik HTTP

Roy Fielding mencipta REST sebagai disertasi kedoktorannya. 

Selepas membacanya, saya akan menguraikannya kepada tiga elemen asas:

1. Dokumen yang menerangkan statistik objek

2. Mekanisme pengangkutan untuk menghantar keadaan objek berulang-alik antara sistem

3. Satu set operasi untuk dilakukan pada keadaan

Walaupun Roy tertumpu pada HTTP semata-mata, saya tidak nampak mengapa pengangkutan lain tidak dapat digunakan. Berikut ialah beberapa contoh:

• Lekapkan perkongsian WebDAV (WebDAV ialah sambungan HTTP, jadi masih menggunakan HTTP). Salin hamparan (.xls, .xlsx, .csv, .ods) ke dalam folder yang dipasang, di mana setiap baris ialah keadaan baharu/dikemas kini. Tindakan menyalin ke dalam bahagian menunjukkan operasi upserting, nama fail menunjukkan jenis data, dan lajur adalah medan. Pelayan bertindak balas dengan (nama dokumen)-status.(akhiran dokumen), yang menyediakan kunci untuk setiap baris, status, dan mungkin mesej ralat. Dalam kes ini, tidak masuk akal untuk meminta data.

• Gunakan gRPC. Objek yang dihantar ialah dokumen, HTTP ialah pengangkutan, dan nama kaedah jauh ialah operasi. Data boleh disediakan dan diminta.

• Gunakan FTP. Sama seperti WebDAV, ia berasaskan fail. Arahan PUT membingungkan dan arahan GET  sedang meminta. GET hanya menyediakan nama fail, jadi ia biasanya menyediakan semua data jenis yang ditentukan. Ada kemungkinan untuk membenarkan nama fail khas yang menunjukkan penapis berkod keras untuk MENDAPATKAN subset data.

Setiap kali saya melihat pelaksanaan REST di alam liar, mereka sering tidak mengikut HTTP asas semantik, dan saya tidak pernah melihat apa-apa penjelasan yang diberikan untuk ini, hanya sekumpulan pendapat yang berbeza-beza. Tiada satu pun daripada mereka yang saya temui merujuk kepada RFC. Kebanyakan orang menganggap bahawa:

• POST = Buat

• PUT = Kemas kini keseluruhan dokumen

• PATCH = Kemas kini sebahagian daripada dokumen

• GET = Dapatkan semula keseluruhan dokumen

Ini bertentangan dengan apa yang HTTP nyatakan berkenaan POST dan PUT :

• PUT adalah "buat" atau "kemas kini". GET biasanya mengembalikan apa sahaja yang terakhir PUT. Jika PUT membuat, ia MESTI mengembalikan 201 Created. Jika PUT kemas kini, ia MESTI mengembalikan 200 OK atau 204 Tiada Kandungan. RFC mencadangkan kandungan untuk 200 OK pada PUT hendaklah menjadi status tindakan. Saya fikir adalah baik dalam kes SQL untuk mengembalikan baris baharu daripada penyata pilihan. Ini mempunyai kelebihan bahawa mana-mana lajur yang dijana dikembalikan kepada pemanggil tanpa perlu melakukan GET yang berasingan.

• POST memproses sumber mengikut semantiknya sendiri. RFC lama berkata POST adalah untuk orang bawahan sumber. Semua versi memberikan contoh menyiarkan artikel ke senarai mel; semua versi mengatakan jika sumber dicipta yang 201 Created PERLU dipulangkan.

Saya berpendapat bahawa secara berkesan maksud POST sebenarnya ialah:

• Sebarang manipulasi data kecuali cipta, kemas kini penuh/separa atau padam

• Sebarang operasi yang bukan manipulasi data, seperti:

• Lakukan carian teks penuh untuk baris yang sepadan dengan frasa.

• Jana objek GIS untuk dipaparkan pada peta.

Perkataan MESTI bermaksud anda pelaksanaan hanya mematuhi HTTP jika anda melakukan apa yang dinyatakan. Menggunakan PUT hanya untuk kemas kini jelas tidak akan merosakkan apa-apa, hanya kerana ia tidak mematuhi RFC. Jika anda menyediakan pelanggan yang mengendalikan semua butiran menghantar/menerima data, maka kata kerja yang digunakan tidak akan menjadi masalah kepada pengguna pelanggan.

Saya jenis lelaki yang mahukan alasan untuk tidak mengikuti RFC. Saya tidak pernah memahami kepentingan memisahkan ciptaan daripada kemas kini dalam API REST, lebih daripada dalam apl web. Fikirkan tentang apl telefon bimbit seperti janji temu kalendar, nota, kenalan, dll:

• "Buat" sedang menekan ikon tambah, yang memaparkan borang baharu dengan nilai kosong atau lalai.

• "Kemas Kini" sedang memilih objek dan menekan ikon pensel, yang memaparkan borang penyertaan dengan nilai semasa.

• Setelah borang penyertaan muncul, ia berfungsi betul-betul sama dari segi pengesahan medan.

Jadi mengapa REST API dan hujung hadapan web harus berbeza daripada apl telefon bimbit? Jika berguna untuk pengguna telefon mendapatkan borang kemasukan data yang sama untuk "buat" dan "kemas kini", bukankah ia sama membantu pengguna API dan web?

Jika anda memutuskan untuk menggunakan PUT sebagaimana "buat" atau "kemas kini", dan anda menggunakan SQL sebagai kedai, kebanyakan vendor mempunyai beberapa jenis pertanyaan upsert. Malangnya, itu tidak membantu menentukan masa untuk mengembalikan 200 OK atau 201 Created. Anda perlu melihat maklumat yang diberikan oleh pemandu anda apabila pertanyaan DML dilaksanakan untuk mencari cara membezakan sisipan daripada kemas kini untuk upsert atau menggunakan strategi pertanyaan lain. 

Contoh mudah ialah melaksanakan set kemas kini ... dengan lajur pk = nilai pk. Jika satu baris terjejas, maka baris itu wujud dan dikemas kini; jika tidak, baris itu tidak wujud dan sisipan diperlukan. Pada Postgres, anda boleh memanfaatkan klausa RETURNING , yang sebenarnya boleh mengembalikan apa-apa sahaja, bukan hanya data baris, seperti berikut:

NILAI SQL (...) ON CONFLICT() DO UPDATE SET ( ...) RETURNING (SELECT COUNT() FROMWHERE=) exists" data-lang="text/x-sql" style="box-sizing: border-box;">1

INSERT INTO <table>
VALUES (...)
ON CONFLICT(<pk column>) DO
UPDATE SET (...)
RETURNING (SELECT COUNT(<pk column>) FROM <table> WHERE <pk column> = <pk value>) exists

Geniusnya ialah:

• Subpilihan dalam klausa RETURNING dilaksanakan dahulu, jadi ia menentukan sama ada baris itu wujud sebelum pertanyaan INSERT ON CONFICT UPDATE dilaksanakan Hasil pertanyaan ialah satu lajur bernama "wujud", iaitu 1 jika baris itu wujud sebelum pertanyaan dilaksanakan, 0 jika tidak.

• Klausa RETURNING juga boleh mengembalikan lajur baris, termasuk apa-apa yang dijana yang tidak disediakan.

Anda hanya perlu memikirkan sekali cara untuk menangani jika sisipan atau kemas kini diperlukan dan membuat abstraksi ringkas yang boleh dipanggil oleh semua PUT anda yang mengendalikan 200 OK atau 201 Created.

Satu manfaat bagus menggunakan PUT seperti yang dimaksudkan ialah sebaik sahaja anda melihat POST anda pasti tahu ia bukan pengambilan semula atau kegigihan, dan sebaliknya, anda tahu untuk mencari POST untuk mencari kod bagi sebarang operasi yang bukan pengambilan semula atau kegigihan.

Saya rasa faedah menggunakan PUT dan POST seperti yang diterangkan dalam RFC melebihi apa jua sebab orang ramai menggunakannya dengan cara yang tidak mematuhi RFC.

Atas ialah kandungan terperinci REST dan Semantik HTTP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!