title: Should the response body of GET all parent resource return a list of child resource?
body: <p>Please bear with me if the title is a bit confusing, I will try my best to explain my question below.</p>
  
  <p>Say I have the following two endpoints</p>
  
  <ol>
  <li><p><strong><code>api/companies</code></strong> (returns a list of all companies like below)</p>
  
  <p><code>[{name: "company1", id: 1}, {name: "company2", id: 2}]</code></p></li>
  <li><p><strong><code>api/companies/{companyeId}/employees</code></strong> (returns a list of all employees for a specific company like below)</p>
  
  <p><code>[{name: "employee1", id: 1}, {name: "employee2", id: 2}]</code></p></li>
  </ol>
  
  <p>What the client side needs is a list of companies, each one of which has a list of employees. The result should looks like this:</p>
  
  <pre><code>[
    {
      name: "company1", 
      id: 1, 
      employees: [ {name: "employee1", id: 1}, {name: "employee2", id: 2} ]
    },
    {
      name: "company2", 
      id: 2, 
      employees: [ {name: "employee3", id: 3}, {name: "employee4", id: 4} ]
    },    
  ]
  </code></pre>
  
  <p>There are two ways I can think of to do this:</p>
  
  <ol>
  <li>Get a list of company first and loop through the company list to
  make a api call for each company to get its list of employees. (I'm wondering if this is a better way of design because of <a href="https://en.wikipedia.org/wiki/HATEOAS" rel="nofollow noreferrer">HATEOAS</a> principle if I understand correctly? Because the smallest unit of resource of <code>api/companies</code> is company but not employees so client is expected to discover companies as the available resource but not employees.)</li>
  </ol>
  
  <blockquote>
    <p>a REST client should then be able to use server-provided links dynamically to discover all the available actions and resources it needs</p>
  </blockquote>
  
  <ol start="2">
  <li>Return a list of employees inside each company object and then return a list of companies through <code>api/companies</code>. Maybe add a query parameter to this endpoint called <code>responseHasEmployees</code> which is a boolean default to be <code>false</code>, so when user make a <code>GET</code> through <code>api/companies?responseHasEmployees=true</code>, the response body will have a list of employees inside each company object.</li>
  </ol>
  
  <p>So my question is, which way is a better way to achieve the client side's goal? (Not necessarily has to be the above two.)</p>
  
  <p><strong><em>Extra info that might be helpful</strong>: companies and employees are stored in different tables, and employees table has a <code>company_fk</code> column.</em></p>