對返回列表但需要參數的WebAPI Action方法使用POST或GET

Question

當前，我在每個控制器中都有以下標准功能來處理基本的CRUD操作：

GET /api/todo           Get all to-do items
GET /api/todo/{id}      Get an item by ID
POST /api/todo          Add a new item
PUT /api/todo/{id}      Update an existing item
DELETE /api/todo/{id}   Delete an item

但是，時間到了，我意識到我實際上需要傳遞多個參數來獲取待辦事項列表，該列表在數據庫級別被過濾，而不是檢索所有項目並使用linq。

例如，這就是我決定去做的事情：
在我的控制器中：

// POST: api/todo
[HttpPost]
public IList<TodoItem> Get([FromBody]GetTodoItemsRequest request)
{
    return _todoItemManager.GetTodoItems(request.Name, request.CategoryId);
}

如您所見，我創建了一個名為GetTodoItemsRequest的新模型，該模型將為每個參數都具有一個屬性。 在這種情況下：名稱，類別ID。

我認為在處理多個參數並檢索列表時，最好進行POST並專門為其創建模型。 而不是使用GET並在url中傳遞各種信息。

進行上述操作似乎有些奇怪……msot會將其視為完美的解決方案，還是WebAPI世界中缺少某些東西？

Answer 1

我認為，即使您需要復雜的模型，使用POST方法進行簡單的讀取操作在語義上也是不正確的。 您正在對名為todo的資源進行純查詢，由於許多原因，這實際上應該是GET操作：

1. 它應該是可緩存的： POST請求就其性質而言是不可緩存的，並且緩存是RESTful服務中的重要約束。
2. 它應從語義上指示不會從調用中引起任何副作用 ： GET請求必須是冪等且安全的 POST操作，而應指示某種數據操縱。 您的操作（過濾）既是冪等又安全的，因此應由GET請求自發表示。
3. URI后面的部分? 字符之所以稱為查詢字符串，是因為：它代表進一步指定請求范圍的參數。 好吧，過濾結果不只是這種方法的一個例子嗎？

除此之外，在我看來，如果Name和CategoryId是查詢的必需參數，則可以通過將Name和CategoryId轉換為路由參數的另一個URI更好地表示您的過濾操作：

http://yourhost.com/api/users/{name}/categories/{categoryId}/todos

假設您的name參數（可能是用戶名？）與categories之間存在關系。

相反，如果您的參數是完全可選的，那么最好將它們保留為查詢字符串參數：

http://yourhost.com/api/todos?name=nameValue&categoryId=categoryIdValue

---

旁注：
如果資源代表項目的集合，則應該真正使用復數形式：例如api/todo將返回一個todos數組，因此您應該將其重命名為api/todos 。