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ừ
/getAllPosts /createNewPost /deleteAllRedPosts
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
GET /users/711?activate hoặc GET /users/711/activate
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
dùng /posts thay cho /post dùng /users thay cho /user dùng /products thay cho /product dùng /settings thay cho /setting
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
GET /posts/711/comments/ trả về danh sách các comments của post 771 GET /posts/711/comments/4 trả về comment thứ 4 của post 771
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 as the Engine of Application 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
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
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
GET /posts?status=DELETED Trả về danh sách post đã bị xoá GET /posts?title<=2 Trả về các post có title nhỏ hơn 2
Sorting
Cho phép sắp xếp tăng hoặc giảm cho nhiều trường
GET /posts?sort=-title,+date
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
GET /posts?fields=title,content,status,date
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
GET /posts?offset=10&limit=5
Để 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
Link: <https://yourdomain.com/sample/api/v1/posts?offset=15&limit=5>; rel="next", <https://yourdomain.com/sample/api/v1/posts?offset=50&limit=3>; rel="last", <https://yourdomain.com/sample/api/v1/posts?offset=0&limit=5>; rel="first", <https://yourdomain.com/sample/api/v1/post?offset=5&limit=5>; rel="prev",
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
/blog/api/v1
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
{
"errors": [
{
"userMessage": "Sorry, the requested resource does not exist",
"internalMessage": "No car found in the database",
"code": 34,
"more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
}
]
}
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