title: Using a sub-resource or not?
body: <p>Let's take the following example:  </p>
  
  <p>We want to expose company and employee information from a RESTful API.</p>
  
  <p>Company data should be quite simply:</p>
  
  <pre><code>GET api/v1/companies
  GET api/v1/companies/{id}
  </code></pre>
  
  <p>Employees BELONG to a company, but we still want to retrieve them individually as well, so which solution is best:</p>
  
  <h2><strong>Solution 1: Using sub-resources</strong></h2>
  
  <p>Get all employees for a company:</p>
  
  <pre><code>GET api/v1/companies/{companyId}/employees
  </code></pre>
  
  <p>Get a specific employee:</p>
  
  <pre><code>GET api/v1/companies/{companyId}/employees/{employeeId}
  </code></pre>
  
  <h2><strong>Solution 2: Using an independent resources</strong></h2>
  
  <p>Get all employees for a company:</p>
  
  <pre><code>GET api/v1/employees?companyId={companyId}
  </code></pre>
  
  <p>Get a specific employee:</p>
  
  <pre><code>GET api/v1/employees/{employeeId}
  </code></pre>
  
  <p>Both options seem to have their pros and cons.  </p>
  
  <ul>
  <li><p>With sub-resources, I may not always have the CompanyId on hand when wanting to retrieve an individual employee. </p></li>
  <li><p>With an independent resource, getting all employees for a company should use the sub-resource approach if we want to be RESTful.</p></li>
  </ul>
  
  <p><strong>Otherwise, we could use a mix, but this lacks consistency:</strong></p>
  
  <p>Get all employees for a company:</p>
  
  <pre><code>GET api/v1/companies/{companyId}/employees
  </code></pre>
  
  <p>Get a specific employee:</p>
  
  <pre><code>GET api/v1/employees/{employeeId}
  </code></pre>
  
  <p>What is the best approach to take in such a situation if we want to stay true to RESTful standards?</p>