Hầu hết các API mà tôi đã thấy đều tuyên bố là "RESTful" - tức là tuân thủ các nguyên tắc và ràng buộc của kiến trúc REST. Khái niệm REST là tách cấu trúc API thành các tài nguyên logic. Đã sử dụng các phương thức HTTP GET, DELETE, POST và PUT để hoạt động với các tài nguyên.
Đây là 10 phương pháp hay nhất để thiết kế một RESTful API sạch sẽ:
1. Sử dụng danh từ nhưng không có động từ
Để dễ hiểu, hãy sử dụng cấu trúc này cho mọi tài nguyên:Ø Resource GET
Ø read POST
Ø create PUT
Ø update DELETE
Không sử dụng động từ: /getAllCars, /createNewCar, /deleteAllRedCars
2. Phương thức GET và các tham số truy vấn không được thay đổi trạng thái
Sử dụng các phương thức PUT, POST và DELETE thay vì phương thức GET để thay đổi trạng thái.Không sử dụng GET để thay đổi trạng thái: GET /users/711?active hoặc GET /user/711/active
3. Sử dụng danh từ số nhiều
Không trộn lẫn danh từ số ít và số nhiều. Giữ cho nó đơn giản và chỉ sử dụng danh từ số nhiều cho tất cả các tài nguyên./cars thay vì /car
/users thay vì /user
/products thay vì /product
/settings thay vì /setting
GET /cars/711/drivers/4 Trả về trình điều khiển số #4 cho ô tô 711
/users thay vì /user
/products thay vì /product
/settings thay vì /setting
4. Sử dụng tài nguyên phụ cho các quan hệ
Nếu một tài nguyên có liên quan đến tài nguyên khác sử dụng nguồn phụ. GET /cars/711/drivers/ Trả về danh sách trình điều khiển cho ô tô 711GET /cars/711/drivers/4 Trả về trình điều khiển số #4 cho ô tô 711
5. Sử dụng tiêu đề HTTP cho các định dạng tuần tự hóa
Cả client và server, cần biết định dạng nào được sử dụng cho giao tiếp.Ø Định dạng phải được chỉ định trong HTTP-Header.
Ø Content-Type xác định định dạng yêu cầu.
Ø Accept xác định danh sách các định dạng phản hồi được chấp nhận.
Ø Content-Type xác định định dạng yêu cầu.
Ø Accept xác định danh sách các định dạng phản hồi được chấp nhận.
6. Sử dụng HATEOAS
Hypermedia làm Engine of Application State là một nguyên tắc mà các liên kết siêu văn bản nên được sử dụng để tạo điều hướng tốt hơn thông qua API.{
"Id": 711,
"producer": "bmw",
"model": "X5 ",
"seats": 5,
"drivers": [
{
" id ":" 23 ",
"name":" Stefan Jauker ",
"links":[
"Id": 711,
"producer": "bmw",
"model": "X5 ",
"seats": 5,
"drivers": [
{
" id ":" 23 ",
"name":" Stefan Jauker ",
"links":[
{
"rel":"seft",
"href":"api/v1/drivers/23"
}]
}]
}]
}
7. Cung cấp tính năng filtering, sorting, field selection và paging cho tập hợp
Filtering:
Sử dụng tham số truy vấn duy nhất cho tất cả các trường hoặc ngôn ngữ truy vấn để lọc.GET /cars?Color=red Trả về danh sách ô tô màu đỏ
GET /cars?seats<=2 Returns một danh sách những chiếc xe với tối đa là 2 ghế?
GET /cars?seats<=2 Returns một danh sách những chiếc xe với tối đa là 2 ghế?
Sorting:
? Cho phép tăng dần và giảm dần sắp xếp trên nhiều fields.GET /cars?sort=-manufactorer, +model
câu params trả về này một danh sách những chiếc xe được sắp xếp theo các nhà sản xuất giảm dần và tăng dần các mô hình.
câu params trả về này một danh sách những chiếc xe được sắp xếp theo các nhà sản xuất giảm dần và tăng dần các mô hình.
Selection field
Mobile client chỉ hiển thị một vài thuộc tính trong danh sách. Họ không cần tất cả các thuộc tính của một tài nguyên. Cung cấp cho người tiêu dùng API khả năng chọn các trường được trả về. Điều này cũng sẽ làm giảm lưu lượng mạng và tăng tốc độ sử dụng API.GET /cars Fields=manufactorer,model, id,color
Paging
Sử dụng limit và offset. Nó linh hoạt cho người dùng và phổ biến trong các cơ sở dữ liệu hàng đầu. Giá trị mặc định nên là limit= 20 và offset=0GET /cars?Offset=10&limit=5
Để gửi tổng số mục nhập trở lại người dùng, hãy sử dụng tiêu đề HTTP tùy chỉnh: X-Total-Count.
Liên kết đến trang tiếp theo hoặc trang trước đó cũng phải được cung cấp trong liên kết tiêu đề HTTP. Điều quan trọng là tuân theo các giá trị tiêu đề liên kết này thay vì tạo URL của riêng bạn. Liên kết: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel = "prev",
8. Phiên bản API của bạn
Làm cho Phiên bản API trở nên bắt buộc và không phát hành một API không phiên bản. Sử dụng số thứ tự đơn giản và tránh ký hiệu dấu chấm chẳng hạn như 2.5.Chúng tôi đang sử dụng url để lập phiên bản API bắt đầu bằng ký tự „v“ /blog/api/v1
9. Xử lý lỗi với mã trạng thái HTTP
Thật khó để làm việc với một API bỏ qua việc xử lý lỗi. Việc trả lại HTTP 500 thuần túy với một stacktrace không hữu ích lắm.Sử dụng mã trạng thái HTTP
Tiêu chuẩn HTTP cung cấp hơn 70 mã trạng thái để mô tả các giá trị trả về. Chúng ta không cần tất cả chúng, nhưng nên sử dụng ít nhất một mount là 10.Ø 200 - OK - Eyerything đang hoạt động
Ø 201 - OK - Tài nguyên mới đã được tạo
Ø 204 - OK - Tài nguyên đã được xóa thành công
Ø 304 - Không được Sửa đổi - Máy khách có thể sử dụng dữ liệu đã lưu trong bộ nhớ cache
Ø 400 - Yêu cầu không hợp lệ - Yêu cầu không hợp lệ hoặc không thể được phục vụ. Lỗi chính xác phải được giải thích trong phần tải lỗi. Ví dụ: “JSON không hợp lệ“
Ø 401 - Không được phép - Yêu cầu yêu cầu xác thực người dùng
Ø 403 - Bị cấm - Máy chủ đã hiểu yêu cầu nhưng đang từ chối hoặc quyền truy cập không được phép.
Ø 404 - Không tìm thấy - Không có tài nguyên nào đằng sau URI.
Ø 422 - Thực thể không thể xử lý - Nên được sử dụng nếu máy chủ không thể xử lý ban đầu, ví dụ: nếu hình ảnh không thể được định dạng hoặc các trường bắt buộc bị thiếu trong tải trọng.
Ø 500 - Internal Server Error - Các nhà phát triển API nên tránh lỗi này. Nếu một lỗi xảy ra trong blog bắt toàn cầu, chuỗi này phải được ghi lại và không được trả lại dưới dạng phản hồi.
Sử dụng tải trọng lỗi
Tất cả các trường hợp ngoại lệ phải được ánh xạ trong một trọng tải lỗi. Dưới đây là ví dụ về trọng tải JSON trông như thế nào.{
" Error ": [
{
"userMessage": "Xin lỗi, tài nguyên được yêu cầu không tồn tại",
"internalMessage": "Không tìm thấy ô tô nào trong cơ sở dữ liệu",
"code" : 34,
"more info": "http://dev.mwaysolutions.
" Error ": [
{
"userMessage": "Xin lỗi, tài nguyên được yêu cầu không tồn tại",
"internalMessage": "Không tìm thấy ô tô nào trong cơ sở dữ liệu",
"code" : 34,
"more info": "http://dev.mwaysolutions.
}]
}
10. Cho phép ghi đè phương thức HTTP
Một số proxy chỉ hỗ trợ phương thức POST và GET. Để hỗ trợ một RESTful API với những hạn chế này, API cần có cách ghi đè phương thức HTTP.Sử dụng HTTP Header tùy chỉnh X-HTTP-Method-Override để ghi đè Phương thức POST.
0 Nhận xét