As far as I can tell each individual resource should have only one canonical path. So in the following example what would good URL patterns be?
Take for example a rest representation of Companies. In this hypothetical example, each company owns 0 or more departments and each department owns 0 or more employees.
A department can’t exist without an associated company.
An employee can’t exist without an associated department.
Now I’d find the natural representation of the resource patterns to be.
/companiesA collection of companies – Accepts POST for a new company. Get for the entire collection./companies/{companyId}An individual company. Accepts GET, PUT and DELETE/companies/{companyId}/departmentsAccepts POST for a new item. (Creates a department within the company.)/companies/{companyId}/departments/{departmentId}//companies/{companyId}/departments/{departmentId}/employees/companies/{companyId}/departments/{departmentId}/employees/{empId}
Given the constraints, in each of the sections, I feel that this makes sense if a bit deeply nested.
However, my difficulty comes if I want to list (GET) all employees across all companies.
The resource pattern for that would most closely map to /employees (The collection of all employees)
Does that mean that I should have /employees/{empId} also because if so then there are two URI’s to get the same resource?
Or maybe the entire schema should be flattened but that would mean that employees are a nested top-level object.
At a basic level /employees/?company={companyId}&department={deptId} returns the exact same view of employees as the most deeply nested pattern.
What’s the best practice for URL patterns where resources are owned by other resources but should be query-able separately?