title: REST API Design: Nested Collection vs. New Root
body: <p>This question is about optimal REST API design and a problem I'm facing to choose between nested resources and root level collections.</p>
  
  <p>To demonstrate the concept, suppose I have collections <code>City</code>, <code>Business</code>, and <code>Employees</code>. A typical API may be constructed as follows. Imagine that ABC, X7N and WWW are keys, e.g. guids:</p>
  
  <pre><code>GET Api/City/ABC/Businesses                       (returns all Businesses in City ABC)
  GET Api/City/ABC/Businesses/X7N                   (returns business X7N)
  GET Api/City/ABC/Businesses/X7N/Employees         (returns all employees at business X7N)
  PUT Api/City/ABC/Businesses/X7N/Employees/WWW     (updates employee WWW)
  </code></pre>
  
  <p>This appears clean because it follows the original domain structure - business are in a city, and employees are at a business. Individual items are accessible via key under the collection (e.g. <code>../Businesses</code> returns all businesses, while <code>../Businesses/X7N</code> returns the individual business).</p>
  
  <p>Here is what the API consumer needs to be able to do:</p>
  
  <ul>
  <li>Get businesses in a city <code>(GET Api/City/ABC/Businesses)</code></li>
  <li>Get all employees at a business <code>(GET Api/City/ABC/Businesses/X7N/Employees)</code></li>
  <li>Update individual employee information <code>(PUT Api/City/ABC/Businesses/X7N/Employees/WWW)</code></li>
  </ul>
  
  <p>That second and third call, while appearing to be in the right place, use a lot of parameters that are actually unnecessary.</p>
  
  <ul>
  <li>To get employees at a business, the only parameter needed is the key of the business (<code>X7N</code>).</li>
  <li>To update an individual employee, the only parameter needed it the key of the employee (<code>WWW</code>)</li>
  </ul>
  
  <p>Nothing in the backend code requires non-key information to look up the business or update the employee. So, instead, the following endpoints appear better:</p>
  
  <pre><code>GET Api/City/ABC/Businesses                       (returns all Businesses in City ABC)
  GET Api/Businesses/X7N                            (returns business X7N)
  GET Api/Businesses/X7N/Employees                  (returns all employees at business X7N)
  PUT Api/Employees/WWW                             (updates employee WWW)
  </code></pre>
  
  <p>As you can see, I've created a new <strong>root</strong> for businesses and employees, even though from a domain perspective they are a sub/sub-sub-collection.</p>
  
  <p>Neither solution appears very clean to me.</p>
  
  <ul>
  <li>The first example asks for unnecessary information, but is structured in a way that appears "natural" to the consumer (individual items from a collection are retrieved via lower leafs)</li>
  <li>The second example only asks for necessary information, but isn't structured in a "natural" way - subcollections are accessible via roots</li>
  <li>The individual employee root would not work when adding a new employee, as we need to know which business to add the employee to, which means that call would at least have to reside under the Business root, such as <code>POST Api/Businesses/X7N7/Employees</code>, which makes everything even more confusing.</li>
  </ul>
  
  <p>Is there a cleaner, third way that I'm not thinking of?</p>