mata utama
REST: UI yang mesra pemaju
Pertama sekali, API adalah antara muka pengguna pemaju, jadi ia harus mesra, mudah, mudah digunakan, dan tentu saja menyenangkan; Walaupun ia hanya fail ReadMe yang mudah tetapi ditulis dengan baik, dokumentasi adalah permulaan yang baik. Maklumat yang paling sedikit yang kami perlukan adalah ringkasan skop perkhidmatan dan senarai kaedah dan titik akses. Ringkasan yang baik boleh: & gt; Ia mempunyai dua jenis objek, kenalan dan nota. Setiap kenalan mempunyai atribut asas seperti nama pertama, nama belakang, dan alamat e -mel. Di samping itu, setiap kenalan boleh mempunyai beberapa nota dalam format markdown yang berkaitan dengannya.Kemudian, lebih baik menyenaraikan semua sumber dan operasi yang akan kami laksanakan. Ini boleh dianggap sebagai setara dengan menggambarkan wireframe aplikasi. Berikutan prinsip utama rehat, setiap sumber diwakili oleh URL di mana operasi adalah kaedah HTTP yang digunakan untuk mengaksesnya. Sebagai contoh, GET/API/Kenalan/12 akan mengambil kenalan dengan ID 12, manakala PUT/API/Kenalan/12 akan mengemas kini kenalan yang sama. Senarai kaedah lengkap adalah seperti berikut:
<code>URL HTTP Method Operation /api/contacts GET 返回联系人数组 /api/contacts/:id GET 返回 ID 为 :id 的联系人 /api/contacts POST 添加一个新联系人并返回它（添加了 id 属性） /api/contacts/:id PUT 更新 ID 为 :id 的联系人 /api/contacts/:id PATCH 部分更新 ID 为 :id 的联系人 /api/contacts/:id DELETE 删除 ID 为 :id 的联系人 /api/contacts/:id/star PUT 将 ID 为 :id 的联系人添加到收藏夹 /api/contacts/:id/star DELETE 从收藏夹中删除 ID 为 :id 的联系人 /api/contacts/:id/notes GET 返回 ID 为 :id 的联系人的笔记 /api/contacts/:id/notes/:nid GET 返回 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes POST 为 ID 为 :id 的联系人添加新笔记 /api/contacts/:id/notes/:nid PUT 更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid PATCH 部分更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid DELETE 删除 ID 为 :id 的联系人的 ID 为 :nid 的笔记</code>
Untuk dokumentasi yang lebih lengkap dan profesional, anda boleh mempertimbangkan menggunakan alat seperti Swagger, Apidoc, atau Google API Discovery Service: Pengguna anda akan menyukai anda!
Alat dan Tetapan
Alat utama yang akan saya gunakan untuk membina API adalah kerangka tipis. Kenapa? & gt; [Ia] membantu anda menulis aplikasi web yang mudah dan kuat dan API dengan cepat.
Ini benar. Keupayaan penghalaannya yang kuat menjadikannya mudah untuk menggunakan kaedah selain daripada mendapatkan dan pos, ia memberikan sokongan terbina dalam untuk mengatasi kaedah HTTP (melalui tajuk HTTP dan medan pos tersembunyi) dan boleh disambungkan dengan middleware dan ciri tambahan untuk membolehkan program aplikasi dan API Pembangunan sangat mudah. Bersama -sama dengan Slim, saya menggunakan Idiorm untuk mengakses lapisan pangkalan data dan pembalakan menggunakan monolog. Oleh itu, fail komposer.json kami akan kelihatan seperti ini:
{
"name": "yourname/my-contacts",
"description": "Simple RESTful API for contacts management",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com"
}
],
"require": {
"slim/slim": "*",
"slim/extras": "*",
"slim/middleware": "*",
"monolog/monolog": "*",
"j4mie/paris": "*",
"flynsarmy/slim-monolog": "*"
},
"archive": {
"exclude": ["vendor", ".DS_Store", "*.log"]
},
"autoload": {
"psr-0": {
"API": "lib/"
}
}
}
<code>bootstrap.php
composer.json
README.md
bin/
import
install
lib/
API/
public/
.htaccess
index.php
share/
config/
default.php
db/
logs/
sql/
data/
contacts.sql
users.sql
tables/
contacts.sql
notes.sql
users.sql
ssl/
mysitename.crt
mysitename.key</code>SSL ada di mana -mana
<Directory>
# Required for mod_rewrite in .htaccess
AllowOverride FileInfo
Options All -Indexes
DirectoryIndex index.php index.shtml index.html
<IfModule php5_module="">
# For Development only!
php_flag display_errors On
</IfModule>
# Enable gzip compression
<IfModule filter_module="">
AddOutputFilterByType DEFLATE application/json
</IfModule>
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Directory>
<VirtualHost *:80>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
<IfModule rewrite_module="">
RewriteEngine on
## Throw a 403 (forbidden) status for non secure requests
RewriteCond %{HTTPS} off
RewriteRule ^.*$ - [L,R=403]
</IfModule>
</VirtualHost>
<IfModule ssl_module="">
NameVirtualHost *:443
Listen 443
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
<VirtualHost *:443>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
SSLEngine on
SSLCertificateFile /path/to/MyApp/share/ssl/mysitename.crt
SSLCertificateKeyFile /path/to/MyApp/share/ssl/mysitename.key
SetEnv SLIM_MODE development
</VirtualHost>
</IfModule>
program boot dan pengawal depan
Seperti yang dinyatakan sebelum ini, fail bootstrap.php bertanggungjawab untuk memuatkan tetapan aplikasi dan tetapan autoloader kami.<code>URL HTTP Method Operation /api/contacts GET 返回联系人数组 /api/contacts/:id GET 返回 ID 为 :id 的联系人 /api/contacts POST 添加一个新联系人并返回它（添加了 id 属性） /api/contacts/:id PUT 更新 ID 为 :id 的联系人 /api/contacts/:id PATCH 部分更新 ID 为 :id 的联系人 /api/contacts/:id DELETE 删除 ID 为 :id 的联系人 /api/contacts/:id/star PUT 将 ID 为 :id 的联系人添加到收藏夹 /api/contacts/:id/star DELETE 从收藏夹中删除 ID 为 :id 的联系人 /api/contacts/:id/notes GET 返回 ID 为 :id 的联系人的笔记 /api/contacts/:id/notes/:nid GET 返回 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes POST 为 ID 为 :id 的联系人添加新笔记 /api/contacts/:id/notes/:nid PUT 更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid PATCH 部分更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid DELETE 删除 ID 为 :id 的联系人的 ID 为 :nid 的笔记</code>
Pertama, saya mendapat persekitaran semasa. Jika fail yang dinamakan
{
"name": "yourname/my-contacts",
"description": "Simple RESTful API for contacts management",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com"
}
],
"require": {
"slim/slim": "*",
"slim/extras": "*",
"slim/middleware": "*",
"monolog/monolog": "*",
"j4mie/paris": "*",
"flynsarmy/slim-monolog": "*"
},
"archive": {
"exclude": ["vendor", ".DS_Store", "*.log"]
},
"autoload": {
"psr-0": {
"API": "lib/"
}
}
}
<code>bootstrap.php
composer.json
README.md
bin/
import
install
lib/
API/
public/
.htaccess
index.php
share/
config/
default.php
db/
logs/
sql/
data/
contacts.sql
users.sql
tables/
contacts.sql
notes.sql
users.sql
ssl/
mysitename.crt
mysitename.key</code>
Struktur penghalaan
Slim mempunyai ciri yang bagus yang dipanggil kumpulan laluan. Menggunakan ciri ini, kami boleh menentukan laluan aplikasi kami seperti ini:
<Directory>
# Required for mod_rewrite in .htaccess
AllowOverride FileInfo
Options All -Indexes
DirectoryIndex index.php index.shtml index.html
<IfModule php5_module="">
# For Development only!
php_flag display_errors On
</IfModule>
# Enable gzip compression
<IfModule filter_module="">
AddOutputFilterByType DEFLATE application/json
</IfModule>
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Directory>
<VirtualHost *:80>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
<IfModule rewrite_module="">
RewriteEngine on
## Throw a 403 (forbidden) status for non secure requests
RewriteCond %{HTTPS} off
RewriteRule ^.*$ - [L,R=403]
</IfModule>
</VirtualHost>
<IfModule ssl_module="">
NameVirtualHost *:443
Listen 443
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
<VirtualHost *:443>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
SSLEngine on
SSLCertificateFile /path/to/MyApp/share/ssl/mysitename.crt
SSLCertificateKeyFile /path/to/MyApp/share/ssl/mysitename.key
SetEnv SLIM_MODE development
</VirtualHost>
</IfModule>middleware JSON
// Init application mode
if (empty($_ENV['SLIM_MODE'])) {
$_ENV['SLIM_MODE'] = (getenv('SLIM_MODE'))
? getenv('SLIM_MODE') : 'development';
}
// Init and load configuration
$config = array();
$configFile = dirname(__FILE__) . '/share/config/'
. $_ENV['SLIM_MODE'] . '.php';
if (is_readable($configFile)) {
require_once $configFile;
} else {
require_once dirname(__FILE__) . '/share/config/default.php';
}
// Create Application
$app = new API\Application($config['app']);<code>URL HTTP Method Operation /api/contacts GET 返回联系人数组 /api/contacts/:id GET 返回 ID 为 :id 的联系人 /api/contacts POST 添加一个新联系人并返回它（添加了 id 属性） /api/contacts/:id PUT 更新 ID 为 :id 的联系人 /api/contacts/:id PATCH 部分更新 ID 为 :id 的联系人 /api/contacts/:id DELETE 删除 ID 为 :id 的联系人 /api/contacts/:id/star PUT 将 ID 为 :id 的联系人添加到收藏夹 /api/contacts/:id/star DELETE 从收藏夹中删除 ID 为 :id 的联系人 /api/contacts/:id/notes GET 返回 ID 为 :id 的联系人的笔记 /api/contacts/:id/notes/:nid GET 返回 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes POST 为 ID 为 :id 的联系人添加新笔记 /api/contacts/:id/notes/:nid PUT 更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid PATCH 部分更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid DELETE 删除 ID 为 :id 的联系人的 ID 为 :nid 的笔记</code>
kita boleh lulus laluan akar ke pembina middleware. Dalam kes ini, saya lulus /API /V1 supaya middleware kami hanya digunakan untuk bahagian API laman web kami. Jika laluan semasa sepadan dengan tajuk Jenis Kandungan Respons, tajuk Jenis Kandungan Respons terpaksa menjadi Aplikasi/JSON, dan saya periksa kaedah permintaan. Jika kaedah permintaan adalah salah satu kaedah permintaan yang membolehkan menulis (meletakkan, menyiarkan, patch), pengepala jenis kandungan permintaan mestilah permohonan/JSON, jika tidak, permohonan itu akan keluar dan memaparkan kod status HTTP jenis 415 yang tidak disokong. Jika semuanya berfungsi dengan baik, pernyataan $ this- & gt; next- & gt; call () akan menjalankan middleware seterusnya dalam rantai.
Pengesahan
Oleh kerana permohonan kami akan dijalankan pada HTTPS secara lalai, saya memutuskan untuk menggunakan kaedah di mana token mengambil keutamaan atas pengesahan asas: kekunci API dihantar ke medan nama pengguna header auth http asas (tiada kata laluan diperlukan)). Untuk melakukan ini, saya menulis kelas middleware yang tipis yang dipanggil Tokenoverbasicauth dengan mengubah suai httpbasicah yang sedia ada. Middleware ini berjalan pertama di dalam rantai, jadi ia ditambah sebagai yang terakhir, dan ia memerlukan parameter laluan akar pilihan dalam pembina.
{
"name": "yourname/my-contacts",
"description": "Simple RESTful API for contacts management",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com"
}
],
"require": {
"slim/slim": "*",
"slim/extras": "*",
"slim/middleware": "*",
"monolog/monolog": "*",
"j4mie/paris": "*",
"flynsarmy/slim-monolog": "*"
},
"archive": {
"exclude": ["vendor", ".DS_Store", "*.log"]
},
"autoload": {
"psr-0": {
"API": "lib/"
}
}
}Kaedah ini mencari Header Permintaan PHP_AUTH_USER untuk Token Auth, dan jika ia tidak wujud atau tidak sah, lulus 401 status dilarang dan tajuk pengesahan kepada pelanggan. Kaedah Verifikasi () dilindungi dan oleh itu boleh ditindih oleh subclass;
<code>bootstrap.php
composer.json
README.md
bin/
import
install
lib/
API/
public/
.htaccess
index.php
share/
config/
default.php
db/
logs/
sql/
data/
contacts.sql
users.sql
tables/
contacts.sql
notes.sql
users.sql
ssl/
mysitename.crt
mysitename.key</code>
muatan ralat yang digunakan
API kami harus memaparkan mesej ralat yang berguna dalam format yang boleh digunakan, sebaik -baiknya dalam perwakilan JSON, jika boleh. Kami memerlukan muatan minimum yang mengandungi kod ralat dan mesej. Di samping itu, kesilapan pengesahan memerlukan lebih banyak segmentasi. Menggunakan Slim, kita boleh mentakrifkan semula 404 kesilapan dan kesilapan pelayan menggunakan kaedah $ App- & gt; notFound () dan $ App- & gt; (), masing-masing.<code>URL HTTP Method Operation /api/contacts GET 返回联系人数组 /api/contacts/:id GET 返回 ID 为 :id 的联系人 /api/contacts POST 添加一个新联系人并返回它（添加了 id 属性） /api/contacts/:id PUT 更新 ID 为 :id 的联系人 /api/contacts/:id PATCH 部分更新 ID 为 :id 的联系人 /api/contacts/:id DELETE 删除 ID 为 :id 的联系人 /api/contacts/:id/star PUT 将 ID 为 :id 的联系人添加到收藏夹 /api/contacts/:id/star DELETE 从收藏夹中删除 ID 为 :id 的联系人 /api/contacts/:id/notes GET 返回 ID 为 :id 的联系人的笔记 /api/contacts/:id/notes/:nid GET 返回 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes POST 为 ID 为 :id 的联系人添加新笔记 /api/contacts/:id/notes/:nid PUT 更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid PATCH 部分更新 ID 为 :id 的联系人的 ID 为 :nid 的笔记 /api/contacts/:id/notes/:nid DELETE 删除 ID 为 :id 的联系人的 ID 为 :nid 的笔记</code>
Ralat tidak dijumpai lebih mudah: Pertama saya mendapatkan jenis media yang diminta, dan kemudian bendera $ ISAPI memberitahu saya jika URL semasa berada di bawah kumpulan /API /V*. Jika pelanggan meminta URL API atau menghantar tajuk Jenis Kandungan JSON, saya akan mengembalikan output JSON, jika tidak, saya boleh membuat templat atau hanya mencetak beberapa HTML statik seperti yang ditunjukkan dalam contoh ini. Kesalahan lain agak rumit, dan kaedah $ App- & gt; () dicetuskan apabila pengecualian berlaku, dan Slim menukarkan ralat PHP standard ke objek ERRORException. Kami memerlukan satu cara untuk memberikan kesilapan yang berguna kepada pelanggan tanpa mendedahkan terlalu banyak mekanisme dalaman untuk mengelakkan kelemahan keselamatan. Untuk aplikasi ini, saya mencipta dua pengecualian adat, apiexception dan apiexceptionvalidationexception, yang terdedah kepada orang ramai, semua jenis pengecualian lain dilog masuk dalam log dan hanya dipaparkan dalam mod pembangunan.
{
"name": "yourname/my-contacts",
"description": "Simple RESTful API for contacts management",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "you@yourdomain.com"
}
],
"require": {
"slim/slim": "*",
"slim/extras": "*",
"slim/middleware": "*",
"monolog/monolog": "*",
"j4mie/paris": "*",
"flynsarmy/slim-monolog": "*"
},
"archive": {
"exclude": ["vendor", ".DS_Store", "*.log"]
},
"autoload": {
"psr-0": {
"API": "lib/"
}
}
}$ app- & gt; () menerima pengecualian yang dibuang sebagai parameter. Secara lalai saya mendapat semua data yang saya perlukan dan mengisi array ralat $, dan kemudian jika saya berada dalam mod pengeluaran, saya tidak dapat menyempurnakan data peribadi dan menulis semula mesej dengan data umum. Kelas ValidationException tersuai mempunyai kaedah getData () tersuai yang mengembalikan pelbagai ralat pengesahan yang ditambah kepada muatan akhir. Kemudian, paparkan ralat dalam JSON atau HTML berdasarkan permintaan. Di sisi API, kita boleh mempunyai ralat mudah seperti berikut:
<code>bootstrap.php
composer.json
README.md
bin/
import
install
lib/
API/
public/
.htaccess
index.php
share/
config/
default.php
db/
logs/
sql/
data/
contacts.sql
users.sql
tables/
contacts.sql
notes.sql
users.sql
ssl/
mysitename.crt
mysitename.key</code>atau ralat pengesahan lengkap seperti yang ditunjukkan di bawah:
<Directory>
# Required for mod_rewrite in .htaccess
AllowOverride FileInfo
Options All -Indexes
DirectoryIndex index.php index.shtml index.html
<IfModule php5_module="">
# For Development only!
php_flag display_errors On
</IfModule>
# Enable gzip compression
<IfModule filter_module="">
AddOutputFilterByType DEFLATE application/json
</IfModule>
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Directory>
<VirtualHost *:80>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
<IfModule rewrite_module="">
RewriteEngine on
## Throw a 403 (forbidden) status for non secure requests
RewriteCond %{HTTPS} off
RewriteRule ^.*$ - [L,R=403]
</IfModule>
</VirtualHost>
<IfModule ssl_module="">
NameVirtualHost *:443
Listen 443
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
<VirtualHost *:443>
ServerAdmin you@yourdomain.com
DocumentRoot "/path/to/MyApp/public"
ServerName myapp.dev
SSLEngine on
SSLCertificateFile /path/to/MyApp/share/ssl/mysitename.crt
SSLCertificateKeyFile /path/to/MyApp/share/ssl/mysitename.key
SetEnv SLIM_MODE development
</VirtualHost>
</IfModule>Kesimpulan
Kami kini mempunyai teras API. Dalam bahagian seterusnya, kami akan menambah beberapa kandungan untuk mempunyai perkhidmatan berfungsi sepenuhnya. Pada masa ini, jangan ragu untuk membaca artikel yang dikaitkan dalam bahagian ini - mereka adalah harta karun prinsip reka bentuk API yang berguna.
Soalan Lazim (FAQ) di bangunan API Rehat dari awal
bagaimana melindungi API REST saya?
bagaimana versi API REST saya?
Pengendalian ralat yang betul dalam API REST meningkatkan kebolehgunaan dan kebolehpercayaannya. Gunakan kod status HTTP untuk menunjukkan jenis ralat. Sertakan mesej ralat dalam badan tindak balas untuk maklumat lanjut mengenai ralat. Ini membantu pelanggan memahami apa yang salah dan bagaimana menyelesaikan masalah.
Uji API REST anda untuk memastikan ia berfungsi seperti yang diharapkan dan boleh mengendalikan pelbagai senario. Anda boleh menggunakan alat seperti Postman atau Curl untuk ujian manual. Untuk ujian automatik, pertimbangkan untuk menggunakan ujian unit, ujian integrasi, dan ujian akhir-ke-akhir. Gunakan pelayan mock untuk mensimulasikan tindak balas API dan menguji bagaimana API anda mengendalikan pelbagai jenis respons.
Dokumentasi yang baik menjadikan API REST anda mudah difahami dan digunakan. Termasuk maklumat terperinci mengenai titik akhir, kaedah permintaan, parameter permintaan, contoh permintaan, kod status tindak balas, dan contoh tindak balas. Anda boleh menggunakan alat seperti Swagger atau Postman untuk menjana dan menjadi tuan rumah dokumen API anda.
Reka bentuk API Restful melibatkan sumber perancangan, titik akhir, dan kaedah. Gunakan kata nama untuk sumber dan kaedah HTTP untuk operasi. Pastikan API mudah dan intuitif. Gunakan kod status untuk menunjukkan hasil permintaan. Buat API anda tanpa statistik, yang bermaksud bahawa setiap permintaan harus mengandungi semua maklumat yang anda perlukan untuk memproses permintaan tersebut.
paging membantu mengehadkan jumlah data yang dikembalikan dalam satu tindak balas. Anda boleh melaksanakan paging menggunakan parameter pertanyaan seperti "halaman" dan "had". Sertakan metadata dalam tajuk atau badan tindak balas untuk menunjukkan halaman semasa, jumlah halaman, jumlah item, dll.
Kadar had melindungi API REST anda dari penyalahgunaan dan memastikan penggunaan yang adil. Anda boleh mengehadkan bilangan permintaan berdasarkan alamat IP, kunci API, atau akaun pengguna anda. Gunakan tajuk HTTP untuk menyampaikan status pembatas kadar kepada pelanggan.
Anda boleh menggunakan API REST anda ke pelayan atau platform awan. Apabila memilih pilihan penempatan, pertimbangkan faktor seperti kos, skalabiliti, dan keselamatan. Gunakan alat integrasi berterusan dan penghantaran berterusan (CI/CD) untuk mengautomasikan proses penempatan. Pantau prestasi dan penggunaan API anda untuk memastikan ia memenuhi keperluan pengguna anda.
Atas ialah kandungan terperinci Bina API rehat dari awal: Pengenalan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!
![[Web front-end] Permulaan pantas Node.js](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
