Nguyên tắc thiết kế API

Việc thiết kế REST API là một việc hết sức khó khăn. Nó không đơn giản như việc chỉ viết ra để cho client gọi là xong. Đôi khi chúng ta gặp những vấn đề là phân vân nên viết API như thế này hay viết như thế kia mặc dù cho tất cả các nghiệp vụ bạn đã xử lý xong. Vì vậy, chúng ta cần phải có các nguyên tắc để thiết kế REST API cho hệ thống để giải quyết các vấn đề đó

Nguyên tắc thứ nhất: Sử dụng HTTP Method để mô tả chức năng của resource

Chúng ta thường sử dụng 4 chức năng như: GET, POST, PUT, DELETE tương đương với các chức năng là đọc, tạo, sửa, xóa.

Nguyên tắc thứ hai: Sử dụng danh từ số nhiều, không sử dụng động từ

Ví dụ:

GET/homes: sử dụng ĐÚNG

/getHomes: sử dụng SAI

Nguyên tắc thứ ba: Chỉ sử dụng danh từ số nhiều

Chúng ta sẽ dùng các REST API như /cars thay vì cho /car

Nguyên tắc thứ tư: Liên kết trong resource

Trong các resource có rất nhiều các quan hệ, vì thế thiết kế REST API sẽ rất đau đầu.

Chúng ta cần phải chia các quan hệ theo các cấp độ của quan hệ.

Ví dụ: chúng ta cần lấy thông tin của comment trong 1 bài đăng của 1 user.

Như vậy, chúng ta thấy user là đối tượng lớn nhất, sau đó đến bài đăng và cuối cùng là comment.

Ta sẽ có 1 API như sau: GET/users/1/posts/3/comments/10

Nguyên tắc thứ năm: Tìm kiếm

Sử dụng attribute là “q” (query)

Ví dụ: GET/cars?q=mercedes

Tìm tất cả ô tô có tên là mercedes

Nguyên tắc thứ sáu: Lựa chọn trường trả về

Sử dụng attribute là “field”

Ví dụ: GET/user?field=id, name, address

Lấy danh sách tất cả các user với các thông tin bao gồm id, name, address

Nguyên tắc thứ 7: HTTP status code

Chuẩn HTTP cung cấp cho ta rất nhiều status code. Chúng ta sẽ không cần biết hết tất cả nhưng ít nhất nên biết đến những status code:

200 OK — Đây là mã HTTP được sử dụng phổ biến nhất để cho thấy rằng hoạt động được thực hiện là thành công.201 CREATED — This can be used when you use POST method to create a new resource.
202 ACCEPTED — Điều này có thể được sử dụng để xác nhận yêu cầu được gửi đến máy chủ.
400 BAD REQUEST — Điều này có thể được sử dụng khi xác nhận đầu vào phía khách hàng không thành công.
401 UNAUTHORIZED / 403 FORBIDDEN — Điều này có thể được sử dụng nếu người dùng hoặc hệ thống không được phép thực hiện một số thao tác nhất định.
404 NOT FOUND — Điều này có thể được sử dụng nếu bạn đang tìm kiếm một số tài nguyên nhất định và nó không có sẵn trong hệ thống.
500 INTERNAL SERVER ERROR — Điều này không bao giờ nên được ném một cách rõ ràng nhưng có thể xảy ra nếu hệ thống bị lỗi.
502 BAD GATEWAY — Điều này có thể được sử dụng nếu máy chủ nhận được phản hồi không hợp lệ từ máy chủ ngược dòng.

Trên đây là những nguyên tắc thiết kế API thường dùng để có thể giúp các bạn không bị mất thời gian hay xảy ra những cuộc tranh cãi về API.

Chúc các bạn thành công!