Thiết kế API REST để cập nhật biểu đồ đối tượng

Question

Tôi đang thiết kế một API REST và đang tìm kiếm phương pháp hay nhất được đề nghị để cập nhật biểu đồ đối tượng. Câu hỏi của tôi được giải thích tốt nhất trong một ví dụ, vì vậy chúng ta hãy nói rằng tôi có một nguồn tài nguyên GET như sau:

URI:/người/123

URI này trả về một đối tượng đồ thị như thế này:

{ 
    "name":"Johnny", 
    "country":{"id":100,"name":"Canada"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"}, 
     {"id":100,"name":"Sports"} 
    ] 
} 

Khi cho phép người tiêu dùng API cập nhật tài nguyên này, bạn mong đợi đối tượng được cập nhật thông qua PUT hoặc PATCH như thế nào? Việc cập nhật thuộc tính "name" khá đơn giản, nhưng tôi không chắc chắn về "country" hoặc "likes", vì người tiêu dùng chỉ có thể thay đổi mối quan hệ với các đối tượng khác và không tạo mối quan hệ mới.

Dưới đây là một cách để yêu cầu cập nhật:

{ 
    "name":"Bob", 
    "countryId":200 
    "likeIds":[3,10,22] 
} 

Bản cập nhật này sẽ thay đổi tài nguyên như sau:

{ 
    "name":"Bob", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":3,"name":"Cars"}, 
     {"id":10,"name":"Planes"}, 
     {"id":22,"name":"Real Estate"} 
    ] 
} 

Thiết kế này một cách rõ ràng và rõ ràng yêu cầu người tiêu dùng để chỉ cập nhật " ID "của" Person ", nhưng tôi lo ngại rằng đồ thị đối tượng cho một PUT/PATCH trông khác với GET, làm cho API khó học và nhớ. Vì vậy, tùy chọn khác là để yêu cầu PUT/PATCH như sau:

{ 
    "name":"Bob", 
    "country":{"id":100}, 
    "likes":[ 
     {"id":3}, 
     {"id":10}, 
     {"id":22} 
    ] 
} 

này sẽ mang lại sự thay đổi tương tự như bản cập nhật trước đó và không làm thay đổi đồ thị đối tượng. Tuy nhiên, nó không làm cho nó rõ ràng cho người tiêu dùng API rằng chỉ có "ID" có thể được cập nhật.

Trong trường hợp này, cách tiếp cận nào được khuyến nghị?

Answer 1

Theo tôi, bạn nên giữ nguyên cấu trúc cho cả hai yêu cầu GET và PUT. Tại sao? Bởi vì nó khá phổ biến để ánh xạ dữ liệu JSON/XML vào các đối tượng và phần lớn (nếu không phải tất cả) phần mềm thực hiện ánh xạ thực sự hoạt động tốt nhất nếu lược đồ JSON luôn giống nhau.

Vì vậy webservice của bạn nên chấp nhận mã JSON sau:

{ 
    "name":"Joe", 
    "country":{"id":200,"name":"United States of America"}, 
    "likes":[ 
     {"id":5,"name":"Fruit"} 
    ] 
} 

Tuy nhiên nó không phải đưa vào tài khoản tên quốc gia và thể tập trung chỉ trên id nước.