Những điểm quan trọng trong thiết kế RESTful API

Chúng ta thường sử dụng thiết kế RESTfull cho web Api. Khái niệm về REST dùng để tách cấu trúc API thành các resource hợp lý. Sử dụng các phương thức HTTP: GET, DELETE, POST và PUT để hoạt động với các resource

Sau đây là 10 điểm lưu ý khi bạn thiết kết một RESTful API

1. Sử dụng danh từ, không sử dụng động từ

Hiểu một cách đơn giản, hãy sử dụng cấu trúc này cho tất cả các resource

Resource GET

Read

POST

Create

PUT

Update

DELETE

 

/posts Trả về một danh sách các post Tạo một post Cập nhập nhiều post cùng một lúc Xoá toàn bộ các post
/posts/1 Trả về thông tin của Post Phương thức này không cho phép trả về 405 Cập nhập thông tin một post xác định Xoá một post xác định

 

Không sử dụng động từ

2. Phương thức GET và các tham số query không nên thay đổi state

Sử dụng phương thức POST, PUT và DELETE để thay đổi state

Không sử dụng GET để thay đổi state

3. Sử dụng danh từ số nhiều

Không nên lẫn lộn giữa danh từ số ít và số nhiều. Giữ nó đơn giản và chỉ sử dụng danh từ số nhiều cho tất cả các resource

4. Sử dụng sub-resource cho các quan hệ

Nếu resource được liên kết đến resource khác thì sử dụng sub-resource

5. Sử dụng HTTP header

Cả Client và Server cần được biết định dạng dữ liệu đang truyền đi là gì. Định dạnh này phải được quy định trong HTTP header

Content-type định nghĩa định dạng của request

Accept định nghĩa danh sách các định dạng của Respone được chấp nhận

6. Sử dụng HATEOAS

HATEOAS(Hypermedia athe Engine oApplication State) là nguyên tắc hypertext link nên được dùng để tạo một điều hướng tốt hơn qua API

7. Cung cấp lựa chọn các trường, filtering, sorting và paging cho các collection

Filtering

Sử dụng một tham số truy vấn duy nhất cho tất cả các trường hoặc ngôn ngữ truy vấn cho filtering

Sorting

Cho phép sắp xếp tăng hoặc giảm cho nhiều trường

Trả về danh sách các post được sắp xếp theo title giảm và date tăng.

Lựa chọn các trường

Các ứng dụng mobile chỉ hiển thị một vài thuộc tính trong danh sách. Chúng không cần tất cả các thuộc tính của resource. Đưa một API để khách hàng có thể lựa chọn các trường trả về. Điều này giúp giảm lưu lượng mạng và tăng tốc độ khi sử dụng API

Paging

Sử dụng limit và offset. Nó là linh hoạt đối với người sử dụng và phổ biến trong database. Mặc định nên đặt limit=20 và offset=0

Để gửi toàn bộ số bản ghi về phía người dùng sử dụng HTTP header cho phép tuỳ chỉnh: X-Total-Count

Link đến trang trước hoặc trang tiếp theo cũng nên được cung cấp trong link của HTTP header. Điều quan trọng là phải tuân theo các giá trị link header này thay vì xây dựng các URL của riêng bạn

8. API version

Đặt một API version là bắt buộc và không nên release API không có version, sử dụng số thứ tự đơn giản và tránh dùng dấu chấm như là 2.5

9. Xử lý lỗi với mã trạng thái HTTP

Rất khó để làm việc với các API mà bỏ qua phần xử lý lỗi. Trả về HTTP 500 thuần tuý với stacktrace (thông tin lỗi không rõ ràng, khó hiểu) là rất không hữu ích.

Sử dụng mã trạng thái HTTP

Chuẩn HTTP cung cấp hơn 70 mã trạng thái để miêu tả các giá trị trả về. Chúng ta không cần sử dụng toàn bộ chúng, nhưng nên sử dụng ít nhất một trong 10 trạng thái sau

200 – OK – Mọi thứ đang hoạt động

201 – OK – resource mới đã được tạo

204 – OK – resource đã được xoá thành công

304 – Not Modified – Client có thể sử dụng dữ liệu được lưu trong cache

400 – Bad Request – request là không hợp lý hoặc có thể không được xử lý. Thông tin lỗi nên được giải thích rõ ràng trong payload ví dụ “The JSON is not valid”

401 – Unauthorized – request yêu cầu có xác thực người dùng

403 – Forbidden – Server hiểu reuqest nhưng từ chối nó hoặc truy cập không được cho phép

404 – Not found – Không có resource nào đằng sau URI

422 – Unprocessable Entity – Nên được sử dụng nếu server không thể xử lý entity, ví dụ, định dạng image không đúng hoặc các trường bắt buộc bị thiếu trong payload

500 – Internal Server Error – Lập trình viên API nên bỏ qua lỗi này, Nếu một lỗi xảy ra, stracktrace nên được log lại và không nên trả về trong response

Sử dụng payload lỗi

Tất cả các Exception nên được phản ánh trong payload. Đây là một ví dụ về payload sẽ trông như thế nào

10. Cho phép ghi đè phương thức HTTP

Một vài Proxy chỉ hỗ trợ phương thức GET và POST. Để hỗ trợ API với những giới hạn này, API cần có cách để ghi đè phương thức HTTP

sử dụng HTTP header tuỳ chỉnh X-HTTP-Method-Override để ghi đè phương thức POST

 

 

 

About the Author: Nguyen Dinh Thuc

Leave a Reply

avatar
  Subscribe  
Notify of