title: RESTful API - Designing sub-resources
body: <p>I am designing a RESTful API and I came up with a problem related to sub-resources.</p>
  
  <p>I see other APIs using full URL to operate over sub-resources. Take the example where <code>Company has Departments</code> and <code>Department has Employees</code>.</p>
  
  <p>In the beginning I though about implementing all possible URLs. Resulting on the following:</p>
  
  <p><strong>Approach A</strong></p>
  
  <pre><code>01. ### COMPANY URLS ###
  02. DELETE /companies/{companyId}
  03. GET    /companies/{companyId}
  04. POST   /companies
  05. PUT    /companies/{companyId}
  06. 
  07. ### DEPARTMENT URLS ###
  08. DELETE /companies/{companyId}/departments/{departmentId}
  09. GET    /companies/{companyId}/departments/{departmentId}
  10. POST   /companies/{companyId}/departments
  11. PUT    /companies/{companyId}/departments/{departmentId}
  12. DELETE /departments/{departmentId}
  13. GET    /departments/{departmentId}
  14. PUT    /departments/{departmentId}
  15. 
  16. ### EMPLOYEE URLS ###
  17. DELETE /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
  18. GET    /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
  19. POST   /companies/{companyId}/departments/{departmentId}/employees
  20. PUT    /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
  21. DELETE /departments/{departmentId}/employees/{employeeId}
  22. GET    /departments/{departmentId}/employees/{employeeId}
  23. POST   /departments/{departmentId}/employees
  24. PUT    /departments/{departmentId}/employees/{employeeId}
  25. DELETE /employees/{employeeId}
  26. GET    /employees/{employeeId}
  27. PUT    /employees/{employeeId}
  </code></pre>
  
  <p>As you can see, there are many URLs which do the same thing. Example: 08 is duplicated of 12; 09 is duplicated of 13; 17 is duplicated of 21 and 25...</p>
  
  <p>I want to remove the duplication but keep consistency. So, re-designed the API with a principle in mind <code>sup-resources are fine but sub-sub-resources are not</code>. Which resulted on the following:</p>
  
  <p><strong>Approach B</strong></p>
  
  <pre><code>01. ### COMPANY URLS ###
  02. DELETE /companies/{companyId}
  03. GET    /companies/{companyId}
  04. POST   /companies
  05. PUT    /companies/{companyId}
  06. 
  07. ### DEPARTMENT URLS ###
  08. DELETE /departments/{departmentId}
  09. GET    /departments/{departmentId}
  10. GET    /companies/{companyId}/departments
  11. POST   /companies/{companyId}/departments
  12. PUT    /departments/{departmentId}
  13. 
  14. ### EMPLOYEE URLS ###
  15. DELETE /employees/{employeeId}
  16. GET    /employees/{employeeId}
  17. GET    /departments/{departmentId}/employees
  18. POST   /departments/{departmentId}/employees
  19. PUT    /employees/{employeeId}
  </code></pre>
  
  <p><strong>My Questions</strong></p>
  
  <p>Q1. Is <em>Approach B</em> considered RESTful? (I am assuming yes)</p>
  
  <p>Q2. Are there pitfalls <em>Approach B</em> I should consider, assuming that documentation is also provided?</p>
  
  <p>Bonus points if you point to other APIs following <em>Approach B</em>.</p>
  
  <p><strong>EDIT</strong></p>
  
  <p><code>Elad Tabak</code> presented good insights.</p>
  
  <p>I fond some API using <em>Approach B</em>:</p>
  
  <p><a href="https://developers.google.com/youtube/v3/docs/" rel="noreferrer">https://developers.google.com/youtube/v3/docs/</a></p>
  
  <p><a href="https://developer.github.com/guides/getting-started/" rel="noreferrer">https://developer.github.com/guides/getting-started/</a></p>
  
  <p><a href="https://dev.twitter.com/rest/public" rel="noreferrer">https://dev.twitter.com/rest/public</a></p>