title: How to update a collection in Web API?
body: <p>I have a basic <code>Order</code>-<code>OrderItem</code> situation and I'm struggling how to update Items in one request (or if should I?) Let me explain and I'm gonna ask the question at the end.</p>
  
  <p><strong>Models:</strong></p>
  
  <pre><code>public class Order
  {
      public int OrderId { get; set; }
      public string CustomerId { get; set; }
      public bool IsVoided { get; set; }
  
      public List&lt;OrderItem&gt; Items { get; set; }
  }
  
  public class OrderItem
  {
      public int OrderItemId { get; set; }
      public string Name { get; set; }
      public int Quantity { get; set; }
      public int Price { get; set; }
  }
  </code></pre>
  
  <p><strong>Use cases I want to cover:</strong></p>
  
  <ol>
  <li>Add <code>Order</code> with lots of <code>OrderItems</code></li>
  <li>Update <code>Order</code>'s properties, like <code>IsVoided</code></li>
  <li>Update <code>Order</code>'s items (multiple items at once). Meaning - user will change multiple items in the UI and the request will be sent when pressed "Save". That includes, updating the current items, but also adding new items or removing items as well. Partial success shouldn't be allowed.</li>
  </ol>
  
  <p><strong>API's URIs to cover each use case:</strong></p>
  
  <ol>
  <li>Add <code>Order</code> with lots of <code>OrderItems</code>: <code>[POST] /api/orders/</code> with payload:</li>
  </ol>
  
  <blockquote>
  <pre><code>{
      "customerId": 805,
      "isVoided": "false",
      "items": [
          {
              "itemId": 112233,
              "quantity": 25,
              "price": 50
          },
          {
              "itemId": 445566,
              "quantity": 20,
              "price": 40
          }
      ]
  }
  </code></pre>
  </blockquote>
  
  <ol start="2">
  <li>Update <code>Order</code>'s properties, like <code>IsVoided</code> (but NOT items): <code>[PATCH] /api/orders/{orderId}</code></li>
  </ol>
  
  <blockquote>
  <pre><code>[
    {
        "op": "replace",
        "path": "/IsVoided",
        "value": true
    }
  ]
  </code></pre>
  </blockquote>
  
  <ol start="3">
  <li>Update <code>Order</code>'s items (multiple items at once)</li>
  </ol>
  
  <p>Here's the problem I'm having... I have a few ideas:</p>
  
  <p><strong>Solution A:</strong> Update Order's items one by one, so endpoints:</p>
  
  <ul>
  <li><code>[POST] /api/orders/{orderId}/items</code>, with payload: <code>{ "quantity": 25, "price": 50 }</code></li>
  <li><code>[PUT] /api/orders/{orderId}/items/{itemId}</code>, with payload: <code>{ "quantity": 25, "price": 50 }</code></li>
  <li><code>[DELETE] /api/orders/{orderId}/items/{itemId}</code></li>
  </ul>
  
  <p>Pros: Clean architecture. You Add/Update/Delete the actually Entity, using Entity's endpoint.</p>
  
  <p>Cons: If user updates 500 items and click "Save", it will result in 500 requests to the server. Also, it will accept partial success</p>
  
  <p><strong>Solution B:</strong> Update Order's items at once by updating the Order:  <code>[PUT] /api/orders/{orderId}</code> with payload:</p>
  
  <blockquote>
  <pre><code>{
      "customerId": 805,
      "isVoided": "false",
      "items": [
          {
              "itemId": 112233,
              "quantity": 25,
              "price": 50
          },
          {
              "itemId": 445566,
              "quantity": 20,
              "price": 40
          }
      ]
  }
  </code></pre>
  </blockquote>
  
  <p>Pros: Performance, Partial success will not be allowed.</p>
  
  <p>Cons: If user updates 50 items, deletes 50 and adds new 50 items to the order, in one request (a <code>PUT</code> request on the <code>Order</code> entitiy) we will esentially add, update, remove 50 items on a different entity - <code>OrderItem</code>. I'm concerned if this is the good <code>RESTful</code> practice.</p>
  
  <p><strong>Solution C:</strong> Update Order's items at once by updating... the collection:  <code>[PUT] /api/orders/{orderId}/items</code> with payload:</p>
  
  <blockquote>
  <pre><code>[
      {
          "itemId": 112233,
          "quantity": 25,
          "price": 50
      },
      {
          "itemId": 445566,
          "quantity": 20,
          "price": 40
      }
  ]
  </code></pre>
  </blockquote>
  
  <p>The collection in the payload, will completely replace the collection in the system, including Add and Remove operations.</p>
  
  <p>Pros: Performance, Partial success will not be allowed, You don't mess with the parent Entity.</p>
  
  <p>Cons: Is this a good practice to call <code>PUT</code> request on a collection. Ususally when you have <code>PUT</code>, the URI ends with some kinda ID (you're updating an entitiy). In this case, the URI will end with "items". Is this how it's done?</p>
  
  <p><strong>Solution D:</strong> A different solution, possibly with <code>PATCH</code>? Never done that before, but maybe it's possible to send <code>PATCH</code> for an <code>Order</code> entity, patching the collection of Items. In JsonDocument's value, I would pass the collection of new items, items to remove and updated items? </p>
  
  <p><strong>So, my question is: Which of these solution is the best for this situation? A, B, C or (if exists)D? Or other solution I didn't think about?</strong></p>