Các API ReSTful được sử dụng chủ yếu bởi các hệ thống khác, đó là lý do tại sao tôi đặt dữ liệu phân trang trong các tiêu đề phản hồi. Tuy nhiên, một số người tiêu dùng API có thể không có quyền truy cập trực tiếp vào các tiêu đề phản hồi hoặc có thể đang xây dựng một UX qua API của bạn, vì vậy việc cung cấp một cách để truy xuất (theo yêu cầu) siêu dữ liệu trong phản hồi JSON là một lợi thế.
Tôi tin rằng việc triển khai của bạn nên bao gồm siêu dữ liệu có thể đọc được bằng máy làm mặc định và siêu dữ liệu có thể đọc được của con người khi được yêu cầu. Siêu dữ liệu mà con người có thể đọc được có thể được trả lại với mọi yêu cầu nếu bạn thích hoặc tốt hơn là theo yêu cầu thông qua tham số truy vấn, chẳng hạn như include=metadatahoặc include_metadata=true.
Trong trường hợp cụ thể của bạn, tôi sẽ bao gồm URI cho từng sản phẩm có bản ghi. Điều này giúp người tiêu dùng API dễ dàng tạo liên kết đến các sản phẩm riêng lẻ. Tôi cũng sẽ đặt một số kỳ vọng hợp lý theo giới hạn yêu cầu phân trang của mình. Việc triển khai và ghi lại các cài đặt mặc định cho kích thước trang là một thực tiễn có thể chấp nhận được. Ví dụ: API của GitHub đặt kích thước trang mặc định thành 30 bản ghi với tối đa 100 bản ghi, đồng thời đặt giới hạn tỷ lệ về số lần bạn có thể truy vấn API. Nếu API của bạn có kích thước trang mặc định, thì chuỗi truy vấn có thể chỉ định chỉ mục trang.
Trong trường hợp con người có thể đọc được, khi điều hướng đến /products?page=5&per_page=20&include=metadata, phản hồi có thể là:
{
"_metadata":
{
"page": 5,
"per_page": 20,
"page_count": 20,
"total_count": 521,
"Links": [
{"self": "/products?page=5&per_page=20"},
{"first": "/products?page=0&per_page=20"},
{"previous": "/products?page=4&per_page=20"},
{"next": "/products?page=6&per_page=20"},
{"last": "/products?page=26&per_page=20"},
]
},
"records": [
{
"id": 1,
"name": "Widget #1",
"uri": "/products/1"
},
{
"id": 2,
"name": "Widget #2",
"uri": "/products/2"
},
{
"id": 3,
"name": "Widget #3",
"uri": "/products/3"
}
]
}
Đối với siêu dữ liệu có thể đọc được bằng máy, tôi sẽ thêm tiêu đề Liên kết vào phản hồi:
Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last
(giá trị tiêu đề Liên kết phải được mã hóa nhanh)
... và có thể là total-counttiêu đề phản hồi tùy chỉnh , nếu bạn chọn:
total-count: 521
Dữ liệu phân trang khác được tiết lộ trong siêu dữ liệu tập trung vào con người có thể không cần thiết đối với siêu dữ liệu tập trung vào máy móc, vì tiêu đề liên kết cho tôi biết tôi đang ở trang nào và số lượng mỗi trang và tôi có thể nhanh chóng truy xuất số lượng bản ghi trong mảng . Do đó, tôi có thể sẽ chỉ tạo một tiêu đề cho tổng số. Bạn luôn có thể thay đổi quyết định sau đó và thêm nhiều siêu dữ liệu hơn.
Ngoài ra, bạn có thể nhận thấy tôi đã xóa /indexkhỏi URI của bạn. Một quy ước chung được chấp nhận là để điểm cuối ReST của bạn hiển thị các bộ sưu tập. Có /indexmột chút lầy lội ở cuối.
Đây chỉ là một vài thứ tôi muốn có khi sử dụng / tạo một API. Hy vọng rằng sẽ giúp!