子資源創建 url

Question

假設我們有一些main-resource和一個具有 1-n 關系的相關sub-resource ；

API 的用戶可以：

1. 列出主要資源，以便GET /main-resources端點。
2. 列出子資源，以便GET /sub-resources端點。
3. 列出main-resource資源的子資源，因此其中之一或兩者；
   1. GET /main-resources/{main-id}/sub-resources
   2. GET /sub-resouces?main={main-id}
4. 在main-resource資源下創建sub-resource資源
   1. POST /main-resource/{main-id}/sub-resouces ：具有層次結構的好處，但為了支持這一點需要提供另一組端點（列表、創建、更新、刪除）。
   2. POST /sub-resouces?main={main-id} ：它的好處是在 URL 中嵌入了 id。中間件可以處理並將提供的值注入請求本身。
5. 在 body POST /sub-resources sub-resource創建一個包含所有參數的子資源

提供一個嵌入了main={main-id}查詢參數的 URI 是解決這個問題的好方法，還是我應該使用分層 URI 的路由 go？

Answer 1

在真正的 REST 環境中，URI 的拼寫並不重要，只要 URI 中使用的字符符合 URI 規范即可。 雖然 RFC 3986 指出

路徑組件包含數據，通常以分層形式組織，與非分層查詢組件（第 3.4 節）中的數據一起，用於識別 URI 方案和命名機構（如果有）的 scope 內的資源。 該路徑以第一個問號（“？”）和井號（“#”）字符結束，或者以 URI 結尾結束。 （來源）

state 不是必須為 URI 分配層次結構。 作為一個整體的 URI 是指向資源的指針，因此各種 URI 的組合可能給人以某種層次結構的印象。 URI 是否具有某種層次結構的實際信息應該源於附加到 URI 的鏈接關系。 這些可以是注冊名稱，如up 、 fist 、 last 、 next 、 prev等或Web 鏈接擴展名，如https://acme.org/rel/parent ，它更像是語義 Web 關系中的謂詞，基本上說明URI at hand 是當前資源的父級。 不過不要將 rel-URI 與真正的 URI 混淆。 此類 rel-URI 不一定需要指向實際資源甚至文檔。 這種鏈接關系擴展雖然可以由媒體類型或某些配置文件定義。

在理想情況下，URI 僅用於將請求發送到實際服務器。 客戶端不會解析或嘗試從 URI 中提取一些知識，因為它會使用伴隨的鏈接關系名稱來確定 URI 是否與手頭的任務相關。 REST 充滿了這種“間接”機制，以幫助將客戶端與服務器解耦。

即像https://acme.org/api/users/1和https://acme.org/api/3f067d90-8b55-4b60-befc-1ce124b4e080這樣的 URI 有什么區別？ 在第一種情況下，開發人員可能會想創建一個用戶 object 來表示調用的 URI 返回的數據。 隨着時間的推移，響應格式可能會因為內容被重命名、刪除和替換為其他內容而中斷。 這就是 Fielding 所說的 REST 不應該擁有的類型化資源。

第二個 URI 不會讓您知道它返回什么內容，您可能會開始質疑它帶來的好處。 雖然您可能不知道服務為此類 URI 返回的實際內容是什么，但您至少知道您的客戶端能夠以某種方式處理數據，否則服務會以406 Not Acceptable響應進行響應。 因此，內容類型協商確保您的客戶端能夠高度確定地接收它能夠處理的數據。 在可能隨時間變化的域中保持互操作性是 REST 的強大優勢和賣點之一。 根據您的客戶端和服務的能力，您可能會收到定制的響應格式，僅適用於該特定服務，或者收到更通用的格式，如 HTML 即。 您的客戶基本上需要一個映射來將接收到的表示格式轉換為您的應用程序可以使用的格式。 如前所述，REST 可能就是為了將客戶端與服務器解耦而引入間接尋址。 然而，這種間接的好處是，一旦你讓它工作，它不僅可以處理從該服務器發出的響應，還可以處理任何其他也支持返回該媒體類型格式的服務。 想一想當您的客戶支持幾種通用格式時，您的客戶有哪些選擇。 然后它基本上可以與該生態系統中的各種其他服務進行通信和互操作，而無需您觸摸它。 這就是幾十年來瀏覽器在 Web 上運行的方式。

這就是為什么我認為菲爾丁的這句話可能是最重要的短語之一，但也是 REST 領域中大多數人忽略或誤解的短語：

REST API 應該花費幾乎所有的描述性努力來定義用於表示資源和驅動應用程序 state 的媒體類型，或者為現有標准媒體類型定義擴展關系名稱和/或支持超文本的標記。 （ 來源）

因此，在真正的 REST 環境中，URI 的形式並不重要，因為客戶端依賴其他機制來確定是否使用該 URI。 即使對於並不真正關心 REST 的真正含義並將其視為老式 RPC 的所謂“REST API”，手頭的問題也可能非常自以為是，並且可能沒有適合所有解決方案的解決方案。 如果您的框架支持根據某些查詢參數的存在注入內容，請使用它。 如果您更喜歡 URI 的更多層次結構，則可以使用 go。 在這種情況下沒有對錯之分。

Answer 2

根據 URI 標准，當資源之間存在層次關系時，最好將其添加到路徑而不是查詢。 https://datatracker.ietf.org/doc/html/rfc3986#page-22有時最好描述關系本身，而不僅僅是子資源，但只有當子資源可以屬於多個主資源時才會發生這種情況resources，也就是n:m的關系。