如何定義我的REST API？

Question

我有3個模型： 錦標賽 ， 冠軍和競爭對手 ：

• 錦標賽有許多冠軍 ;
• 錦標賽屬於錦標賽 ;
• 冠軍有許多競爭對手 。

因此，要列出所有錦標賽的所有競爭對手，URL為：

GET https://base.com/tournament/{slug}/competitors

但是要增加一個競爭對手，它與冠軍有關，所以：

POST  https://base.com/championships/{id}/competitors

對於相同的模型，兩個動詞（GET和POST）具有不同的URI可以嗎？ 否則，我該怎么辦？

我喜歡這樣做：

POST  https://base.com/tournaments/{slug}/championships/{id}/competitors 

沒有必填字段。

Answer 1

對於相同的模型，兩個動詞（ GET和POST ）具有不同的URI可以嗎？

這可能會使API使用者感到困惑，因此我建議您使用相同的URI。

---

請記住，在Roy T. Fielding的論文的第5章中描述的REST體系結構樣式為在這種體系結構之上構建的應用程序定義了一組約束 。 但是它並沒有說明URI必須是什么樣。

馬丁·福勒（Martin Fowler）撰寫的熱門文章中的示例解釋了倫納德·理查森（Leonard Richardson）定義的模型，這些示例提出了一種看起來友好且易於閱讀的URI結構。 盡管這可能是理想的 ，但對於REST應用程序不是必需的。

---

您可以選擇許多有效的方法。 如果競爭者要求冠軍存在而冠軍需要錦標賽存在，則可以使用以下方式表達這種等級 ：

/tournaments/{slug}

/tournaments/{slug}/championships/{id}

/tournaments/{slug}/championships/{id}/competitors/{id}

但是最后一個URI可能被認為太長，可能難以記住。 因此，您可以將其拆分，然后就不需要發送許多參數了：

/tournaments/{slug}

/championships/{id}

/competitors/{id}

如果您需要執行任何過濾，則可以使用查詢參數 。 例如：

/championships/{id}?tournament={slug}

Answer 2

提醒：REST不在乎您的URI使用什么拼寫

對於相同的模型，兩個動詞（GET和POST）具有不同的URI可以嗎？ 否則，我該怎么辦？

可以，但是需要支付一定的費用。

讓我們回顧一下菲爾丁不得不說的話（2008年）

REST適用於跨越多個組織的長期基於網絡的應用程序。 REST接口被設計為對於大容量超媒體數據傳輸是高效的，針對Web的常見情況進行了優化，但是導致的接口對於其他形式的體系結構交互不是最佳的。

菲爾丁在論文中指出的一種復制方式是緩存 ; 他繼續將該樣式添加到他對REST的定義中

為了提高網絡效率，我們添加了緩存約束以形成client-cache-stateless-server樣式。...緩存約束要求對請求的響應中的數據被隱式或顯式標記為可緩存或不可緩存。 如果響應是可緩存的，則授予客戶端緩存以將響應數據重新用於以后的等效請求的權限。

在HTTP中，緩存的語義是在RFC 7234中定義的； 第4.4節描述了無效 。

當收到一個非錯誤狀態碼作為響應時，緩存必須使有效的請求URI（[RFC7230]的5.5節）以及位置和內容位置響應頭字段（如果存在）中的URI無效。不安全的請求方法。

這意味着，通過不了解協議細節的通用客戶端進行的通信，可以基於請求和響應中的元數據來使它們的陳舊表示形式的本地副本無效。

（在過去，當我們不對所有流量進行加密時，這是一筆更大的交易；但這仍然適用於（a）客戶端的本地緩存和（b）位於域模型前面的緩存反向代理）。

就REST而言，URI是不透明的。 之間沒有根本的關系

/A
/A/B
/A/B/C
/A/B/D
/A/E

因此，如果緩存看到/A/B應該無效，它們可以這樣做，但對其他URI則不做任何事情。

對於PUT，DELETE，PATCH-這些方法的語義非常特定於有效請求URI。

如果對POST應用相同的方法，則將“免費”獲得緩存失效。

通過一個簡單的例子； 想象一個網站，我們在那里

GET /superCoolResource
GET /superCoolResource/editForm

我們想在/superCoolResource進行一些更改，因此我們加載編輯表單並提交。

POST ...?

如果我們POST到/superCoolResource/editForm ，那么我們告訴客戶端，如果POST成功， 則應該重新加載表單的緩存副本。 但這可能不是我們想要的-表單很可能保持不變，並且/ superCoolResource是更改的對象。 這意味着我們可能要使/superCoolResource為目標URI

GET /superCoolResource/editForm

200 OK

... <form action="/superCoolResource" method="POST"> ....

神奇的是，客戶端的緩存，原始服務器的緩存以及所有專用於對話的中間緩存都知道在POST成功后將其舊版本的/ superCoolResource復制出去。