1. ออกแบบจากภายใน (Inside-Out)
ใช้โครงสร้างภายในมาเปิดเผยผ่าน API เช่น
GET /api/database/tables/book_inventory/records?status=1
GET /api/books?available=true
แนวคิดที่ถูกต้องคือ “นักพัฒนาจะเข้าใจสิ่งนี้ไหม ถ้าไม่รู้โครงสร้างระบบเราเลย?”
.
2. นิยาม URI ไม่ดี
หลีกเลี่ยงการใส่ verb ใน URL:
ตัวอย่าง:
GET /api/getUsers → GET /api/users
POST /api/createOrder → POST /api/orders
หลีกเลี่ยงการซ้อนโครงสร้างซับซ้อนเกินไป:
GET /api/companies/456/departments/2/employees/123/projects
GET /api/projects?employeeId=123
.
3. ใช้ HTTP Methods ผิด
ออกแบบ POST ทุกอย่าง = ไม่ดี
ตัวอย่าง:
POST /api/users/search → GET /api/users?name=Smith
DELETE /api/products/123
.
4. จัดการ Error ไม่ดี
ข้อความ error คลุมเครือ:
ตัวอย่างที่ไม่ดี:
{ “error”: “An error occurred” }
ตัวอย่างที่ดี:
{
“status”: 400,
“code”: “INVALID_PARAMETER”,
“message”: “The email address is improperly formatted”,
“details”: [{ “field”: “email”, “message”: “Must be a valid email address” }]
}
อย่าลืมใช้ HTTP Status Codes ให้เหมาะสม:
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: Server Error
.
5. ไม่จัดการเรื่อง Versioning
รูปแบบการจัด version ที่ดี:
แบบ URL: /api/v1/users
แบบ Header: Accept: application/vnd.company.api+json;version=1
แบบ Query: /api/users?version=1
อย่าลืมทำ document ความเปลี่ยนแปลง และแนวทางการอัปเกรดที่ชัดเจน
.
6. Response ซับซ้อนเกินไป
อย่าส่งทุกอย่างใน response เดียว ควรส่งเฉพาะข้อมูลที่จำเป็น:
ตัวอย่างที่ไม่ดี:
{
“id”: 123, “username”: “jsmith”, “email”: “jsmith@example.com”
}
ให้ใช้ query param เพื่อเลือก fields ที่ต้องการ:
ตัวอย่างที่ดี:
GET /api/users/123?fields=id,name,email
.
7. ละเลย Security
– ไม่ใช้ HTTPS หรือไม่มี token expiration
– ตรวจแค่การ authentication แต่ไม่ตรวจ authorization
– เผยข้อมูลสำคัญ หรือ sensitive data ผ่าน error หรือ response
– ไม่จำกัดอัตราการเรียก (Rate Limiting)
แนวทางที่ดี:
– ใช้ OAuth 2.0
– บังคับ HTTPS
– ตรวจสิทธิ์ทั้ง endpoint และระดับ object
– ใช้ HTTP 429 เมื่อถูกเรียกเกิน quota
.
8. ไม่มีหรือมีเอกสารที่แย่
– นักพัฒนาใช้ไม่ได้ = API ล้มเหลว
เอกสารที่ดีต้องมี:
– วิธีเริ่มต้น
– ตัวอย่าง request/response
– คำอธิบาย error
– SDK/Client library
– เปลี่ยนอะไรในแต่ละเวอร์ชัน
.
ใครที่เริ่มออกแบบหรือเขียน API ลองเอาไปใช้เป็นแนวทางดูนะครับ
โค้ชเอก
