Mẫu tốt nhất để thêm một mục hiện có vào bộ sưu tập trong API REST là gì?

Tôi đang thiết kế API REST thực dụng và tôi hơi băn khoăn về cách tốt nhất để thêm các thực thể hiện có vào bộ sưu tập. Mô hình miền của tôi bao gồm Dự án có bộ sưu tập Trang web. Đây là một mối quan hệ nhiều-nhiều nghiêm ngặt và tôi không cần phải tạo một thực thể mô hình hóa rõ ràng mối quan hệ (ví dụ ProjectSite).

API của tôi sẽ cho phép người tiêu dùng thêm Trang web hiện tại vào Dự án. Nơi tôi đang gác máy là dữ liệu duy nhất tôi thực sự cần là ProjectId và SiteId. Ý tưởng ban đầu của tôi là:

1. POST myapi/projects/{projectId}/sites/{siteId}

Nhưng tôi cũng nghĩ về

2. POST myapi/projects/{projectId}/sites

với một thực thể Trang web được gửi dưới dạng nội dung JSON.

Tùy chọn 1 đơn giản và hoạt động nhưng không cảm thấy hoàn toàn đúng và tôi có các mối quan hệ khác không thể theo mô hình này để nó thêm sự không nhất quán vào API của tôi.

Tùy chọn 2 cảm thấy tốt hơn nhưng dẫn đến hai mối quan tâm:

• Tôi có nên tạo Trang web hay ném ngoại lệ nếu Trang mới được đăng (SiteId = 0) không?
• Vì tôi chỉ cần ProjectId và SiteId để tạo mối quan hệ, nên Trang có thể được đăng với dữ liệu sai hoặc thiếu cho các thuộc tính khác.

Tùy chọn thứ 3 là cung cấp một điểm cuối đơn giản chỉ để tạo và xóa mối quan hệ. Điểm cuối này sẽ mong đợi một tải trọng JSON chỉ chứa ProjectId và SiteId.

Bạn nghĩ sao?

POST là động từ "chắp thêm" và cũng là động từ "đang xử lý". PUT là động từ "tạo / cập nhật" (đối với các định danh đã biết) và gần như có vẻ là lựa chọn đúng ở đây, vì URI mục tiêu đầy đủ đã được biết. projectIdvà siteIdđã tồn tại, vì vậy bạn không cần "POST vào bộ sưu tập" để tạo ID mới.

Vấn đề với PUT là nó đòi hỏi cơ thể phải là đại diện cho tài nguyên mà bạn PUTting. Nhưng mục đích ở đây là nối thêm tài nguyên thu thập "dự án / trang web", thay vì cập nhật tài nguyên Trang web.

Điều gì xảy ra nếu ai đó PUT đại diện JSON đầy đủ của Trang web hiện tại? Bạn có nên cập nhật bộ sưu tập và cập nhật đối tượng? Bạn có thể ủng hộ điều đó, nhưng có vẻ như đó không phải là ý định. Như bạn đã nói,

dữ liệu duy nhất tôi thực sự cần là ProjectId và SiteId

Thay vào đó, tôi sẽ thử POST siteIdbộ sưu tập và dựa vào bản chất "chắp thêm" và "xử lý" của POST:

POST myapi / dự án / {projectId} / trang web

{'ID': '...' }

Vì bạn đang sửa đổi các trang web tài nguyên tuyển tập chứ không phải tài nguyên Trang , đó là URI bạn muốn. POST có thể biết "chắp thêm / xử lý" và thêm phần tử có id đó vào tuyển tập trang của dự án.

Điều đó vẫn để ngỏ khả năng tạo ra các trang web hoàn toàn mới cho dự án bằng cách làm sáng tỏ JSON và bỏ qua id. "Không có id" == "tạo từ đầu". Nhưng nếu URI của bộ sưu tập có id và không có gì khác, thì rõ ràng điều gì cần phải xảy ra.

Câu hỏi thú vị. :)

Chúng tôi sử dụng Patchphương pháp cho những thứ như thế này. Những gì bạn muốn làm là sửa đổi một Dự án hiện có để thêm một Trang web vào đó.

Vì vậy, một cái gì đó như thế này sẽ làm việc

PATCH myapi/projects/{id} 

với thực thể (các) Trang web là JSON / JSONArray trong phần thân yêu cầu.

Bằng cách đó, bạn có thể sử dụng cùng một URL để sửa đổi các phần khác nhau của Dự án nếu bạn cần - mã của bạn trong quá trình triển khai phải đủ thông minh để xử lý việc sửa đổi một phần tài nguyên này.