Saya seorang pengembang dan untuk sebagian besar karir saya, saya telah membangun API untuk berbagai layanan. Panduan untuk artikel ini telah disusun berdasarkan masalah yang paling umum saat mendesain layanan Anda sendiri sebagai tim atau menggunakan API pihak ketiga.
Kemungkinannya adalah, Anda telah menemukan penyedia API yang buruk. Bekerja dengan mereka, sebagai suatu peraturan, dikaitkan dengan peningkatan emosionalitas dan kesalahpahaman. Sebagian besar masalah ini dapat dihindari dengan mendesain antarmuka aplikasi menggunakan tip di bawah ini.
1. Jangan gunakan kata kerja di URL *
* - jika ini adalah salah satu operasi CRUD.
Metode permintaan CRUD bertanggung jawab atas tindakan dengan sumber daya: POST - buat (buat), GET - get (baca), PUT / PATH - perbarui (perbarui), HAPUS - hapus (Anda mengerti). Buruk:
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
Baik:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Gunakan kata kerja di URL
Buruk:
POST /users/{userId}/books/{bookId}/create -
Baik:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3. Sorot entitas baru
Di atas ada contoh menambahkan buku ke pengguna, mungkin logika aplikasi Anda menyiratkan daftar favorit, maka rutenya mungkin seperti ini:
POST /wishlist/{userId}/{bookId}
4. Gunakan satu ID sumber daya *
* - jika struktur data Anda memungkinkan.
Artinya, jika Anda memiliki catatan one-to-many, misalnya,
booking -> traveller (booking-> traveller), Anda cukup memasukkan ID traveller dalam permintaan.
Buruk:
#
GET /bookings/{bookingId}/travellers/{travellerId}
Baik:
GET /bookings/travellers/{travellerId}
Saya juga mencatat bahwa /bookings/travellers/
itu lebih baik daripada hanya /travellers
berpegang pada hierarki data dengan baik di API Anda.
5.
:
GET /user/{userId} -
POST /ticket/{ticketId}/book -
:
GET /users/{userId}
POST /tickets/{ticketId}/book
6. HTTP-
- . . :
400 Bad Request - , , .
401 Unauthorized - .
403 Forbidden - , .
404 Not Found - .
409 Conflict - , .
500 Internal Server Error - .
503 Service Unavailable - .
7.
. , - (quizzes passed_quizzes). , .
: /quizzes
/quizzes/passed
. quizzes
- (), passed
- ().
:
GET /passed-quizzes -
GET /booked-tickets -
POST /gold-users -
:
GET /tickets/booked
POST /users/gold
8.
API - . , , .
:
GET /book/{bookId}
{
"name": "Harry Potter and the Philosopher's Stone",
"genre": "fantasy",
"status": 0, #
"error": false,
...
}
:
GET /book/{bookId}
{
"status": 0,
"message": "ok",
"data": {...}
}
3 . status
, message
- , , . , , . 409 status
message
.
9. json camelCase
9.1 Dalam parameter kueri
Buruk:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
Baik:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 Dalam isi respons atau permintaan yang diterima
Buruk:
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
Baik:
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10. Gunakan Jenis Konten
Buruk:
GET /tickets.json
GET /tickets.xml
Baik:
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
Kesimpulan
Rekomendasi yang tercantum di atas bukanlah daftar lengkap cara untuk membuat API lebih baik. Untuk studi lebih lanjut, saya sarankan Anda mengurai spesifikasi REST API dan daftar kode status http (Anda akan terkejut berapa banyak yang ada dan situasi apa yang dicakupnya).
Dan di komentar, saya sarankan untuk menulis rekomendasi Anda sendiri untuk membangun REST API yang Anda anggap penting.