通過在RESTful API中發布集合來創建項目

Question

我正在嘗試通過設計API來了解REST原理，並盡我所能遵循REST原理。 REST API中非常普遍的做法是通過POST創建資源，如下所示：

{
    "address_1": "123 Main St.",
    "city": "Anywhere",
    "some": "more stuff"
}

要創建地址，你只是POST它： /api/customers/ABC123/addresses

...然后返回類似：

201 Created Location: /api/customers/ABC123/addresses/XYZ789

我認為這很清楚。 但是，如果要一次創建多個地址，例如：

[
   {
      "address_1":"123 Main St.",
      "city":"Anywhere",
      "some":"more stuff"
   },
   {
      "address_1":"456 State St.",
      "city":"Somewhere",
      "some":"more stuff"
   }
]   

在這種情況下，我仍將發布到/api/customers/ABC123/addresses ，但是，由於創建了多個位置，因此無法將位置返回到資源。 但是，我想可以返回集合的位置，例如：

201 Created Location: /api/customers/ABC123/addresses

但是，以我自己使用API​​的經驗來看，似乎我僅遇到一個項目的創建（如我的第一個示例），而沒有遇到一個POST中的多個項目的創建（如我的第二個示例）。 所以，我的問題是：

第二個例子不好嗎？ 如果是這樣，為什么？ 似乎允許在單個POST中創建多個項目會很方便，並且可以減少抖動。

如果第二個例子不是一個壞習慣，那么像我在第二個例子中所示的那樣，返回位置是否合適？

感謝您的任何建議。

Answer 1

在上述情況下，您實質上是在通過添加其他地址來修改客戶資源。 您還添加了一個約束，即您希望能夠一次添加多個地址。

讓我們接受這個要求。

所以你會怎么做？ 與大多數軟件問題一樣。 不一定有最好的解決方案。 這里有一些選擇...

您可以更新整個客戶，例如PUT /api/customers/ABC123 。 也許，客戶首先是GET客戶，然后將新的地址添加到addresss屬性，最后將其放回服務器。 該操作返回200 （您只需調用要返回的位置就無需返回201的位置）。 另外，請記住，對於REST， PUT必須是冪等的，因此一遍又一遍地調用它應始終產生相同的結果。

同樣，（當然有點奇怪）如果客戶資源由於某種原因超大，您可以在/api/customers/ABC123/addresses帶有整個新列表的PUT操作，然后再次返回200 （再次，無需返回您剛剛調用的位置）。

現在，假設事情變得很繁瑣，並且在客戶上進行GET並隨后執行PUT根本無法工作（無論出於何種瘋狂的原因）。 您將獲得要求，要求您僅通過提供新地址就必須提供某種方法來修改地址列表。 在這里， PUT不適合，因為它不是冪等的。 但是POST沒有冪等的要求，因此POST很有道理。 但是，您在Location標頭中返回的位置是什么？ 隨機挑選一些物品是沒有意義的。 返回所有客戶地址的位置也沒有意義。 好吧，幸運的是POST可以提供輸出。 在這種情況下，只需返回狀態200 。 不過，這“ 聞起來 ”。 感覺不舒服。 這是您必須退后一步意識到的時候，嘿，REST很棒！ 但是，這不是靈丹妙葯。 有時候事情並不完美。 在這種情況下，您盡力找到了一種RESTful方式，但是有時，它並不存在。 在這種情況下，您可能需要為該功能部件提供Web服務樣式端點。

• 請參閱有關RESTful設計原則的博客文章

Answer 2

您可以提供任何響應。

您的響應可能是位置的數組或集合，或者是簡單的“成功”或“失敗”字符串，甚至是您希望某些javascript將其放入div中的html表。 您正在構建API，因此可以決定響應的外觀。

有許多工具可以自動將功能轉換為REST端點，因此您可以考慮使用其中之一。 好處是您可以返回某些內容，也許是字符串數組，它會自動將其轉換為xml或json或yaml或任何要求的類型。