title: Update/create hierarchical resources REST
body: <p>I am working on an <code>REST API</code> and I am trying to understand how to deal with hierarchical resources.</p>
  
  <h1>Background</h1>
  
  <p>Let's start with a simple example. In my API I have <strong>Users</strong>, <strong>User profiles</strong> and <strong>Reviews</strong>.</p>
  
  <ul>
  <li><strong>Users</strong> must have a <strong>User Profile</strong> associated (a User Profile corresponds to only one User)</li>
  <li><strong>Users</strong> might have a <strong>Review</strong> associated (a Review corresponds to only one User)</li>
  </ul>
  
  <p>User's resource representation should be:</p>
  
  <pre><code>User: {
     "u1": "u1value", // User's attributes
     "u2": "u2value",
     ...
     "links": [{
         "rel": "profile",
         "href": "http://..." // URI of the profile resource
     }, {
         "rel": "review",
         "href": "http://..." // URI of the review resource
     }]
  }
  </code></pre>
  
  <p>User profile resource representation should be:</p>
  
  <pre><code>UserProfile: {
     "p1": "p1value", // Profile attributes
     "p2": "p2value",
     ...
     "links": [{
         "rel": "owner",
         "href": "http://..." // URI of the user resource
     }]
  }
  </code></pre>
  
  <p>Review resource representation should be:</p>
  
  <pre><code>Review: {
     "r1": "r1value", // Review attributes
     "r2": "r2value",
     ...
     "links": [{
         "rel": "owner",
         "href": "http://..." // URI of the user resource
     }]
  }
  </code></pre>
  
  <p>Resources URIs could be: </p>
  
  <ul>
  <li><code>http://api.example.com/users/{userid}</code>: access to the user resource</li>
  <li><code>http://api.example.com/users/{userid}/profile</code>: access to the user's profile resource</li>
  <li><code>http://api.example.com/users/{userid}/review</code>: access to the user's review resource</li>
  </ul>
  
  <h1>Resource creation: what's the correct way to create a user?</h1>
  
  <p>Now I want to create a new user:</p>
  
  <ol>
  <li><code>POST http://api.example.com/users {"u1": "bar", "u2": "foo"}</code> and I get back the new userid = 42</li>
  <li><code>POST http://api.example.com/users/42/profile {"p1": "baz", "p2": "asd"}</code></li>
  <li><code>PUT http://api.example.com/users {"u1": "bar", "u2": "foo", links: [{"rel": "profile", "href": "http://api.example.com/users/42/profile"]}</code></li>
  </ol>
  
  <p>My concerns:</p>
  
  <ul>
  <li>What if something breaks between 1 and 2 or 2 and 3? </li>
  <li>In 3), should the server update automagically the links in the <a href="http://api.example.com/users/42/profile">http://api.example.com/users/42/profile</a>, to point to the correct owner?</li>
  <li>Updating link fields is the proper manner to create relationships? Or should I skip step 3) and let the system guess the relationships according to URI conventions? (I read on several books that URI should be considered as opaque.)</li>
  </ul>