Cách tốt nhất trong REST api để yêu cầu đại diện tóm tắt của tài nguyên?

Question

Tôi có một API REST giao dịch với một tài nguyên lớn, khách hàng. Khách hàng đôi khi muốn có một đại diện viết tắt/tóm tắt của một khách hàng. Điều gì sẽ là một cách hay để xác định rằng yêu cầu là cho một đại diện tóm tắt?

Để có được một đại diện đầy đủ cho khách hàng 123 của nó: /customers/123

Để có được một đại diện Tóm lại là /customers/123/summary một cách tốt? Có các lựa chọn tốt hơn không?

Answer 1

Để làm cho giải pháp của bạn có thể sử dụng lại và linh hoạt, tôi khuyên bạn nên triển khai tham số truy vấn "bộ lọc". Trong đó, bạn có thể đặt bất kỳ lĩnh vực theo yêu cầu của khách hàng:

GET /customers/123?fields=id,first_name,last_name,email 

cách đó, nếu sau này bạn cần phải tạo ra một bản tóm tắt khác nhau cho một nhiệm vụ khác nhau, bạn sẽ không có bất cứ điều gì để thay đổi.

Tôi sẽ không đề xuất /customers/123/summary vì nó không linh hoạt. Nó có thể là ok cho một trường hợp, nhưng nếu khách hàng cần truy cập các thuộc tính khác nhau cho một trường hợp khác, bạn sẽ phải tinh chỉnh tài nguyên (rất có thể bằng cách trả về nhiều trường hơn mức cần thiết). Nếu bạn muốn "giấu" các tên trường, có lẽ một sự thay thế có thể là một cái gì đó như thế này:

GET /customers/123?view=DESCRIPTION 

đâu "DESCRIPTION" sẽ mô tả các loại tóm tắt. Ví dụ:

GET /customers/123?view=addresses_only // eg. returns billing and home address 
GET /customers/123?view=short // eg. returns only id, first name, last name 

Điều này vẫn linh hoạt vì bạn có thể dễ dàng tạo chế độ xem mới.