title: How to handle updates in a REST API?
body: <p>I'd like some perspective about ways to perform writes using a RESTful API. For this example, assume a Person object:</p>
  
  <pre><code>{
      "id": 1,
      "name": "Example Person",
      "addresses": [
          {
              "id": 11,
          }
      ],
      "friends": [
          {
              "id": 21,
              "name": "John"
          }
      ]    }
  </code></pre>
  
  <p>There's a /people API that serves up objects like these. You could GET /people/123 to retrieve the above example. What I'm concerned about, though, are writes. Conventionally, updating an object like this via a REST API is done by sending a PATCH or PUT to /people/123 with the new state of the object. However, you could potentially be doing one or many things in your update:</p>
  
  <ul>
  <li>Change the person's name</li>
  <li>Update an existing address</li>
  <li>Add a new address</li>
  <li>Remove an address</li>
  <li>Update an existing friend</li>
  <li>Add an existing person as a new friend</li>
  <li>Stop being friends with someone</li>
  </ul>
  
  <p>Each one of these is a different action that may have different logic associated with it. For example, if someone adds you as a friend, you should get a notification about it, whereas adding an address shouldn't generate any kind of notification.</p>
  
  <p>When communicating with a REST API, is there value in sending a list of actions to take instead of just sending the new state of the object and asking the API to figure out what actions the user intended to perform based on that?</p>