api design - What are best practices for REST nested resources?

Question

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 an 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.

• /companies A collection of companies - Accepts put for a new company. Get for the entire collection.
• /companies/{companyId} An individual company. Accepts GET, PUT and DELETE
• /companies/{companyId}/departments Accepts 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?

Answer 1

I've tried both design strategies - nested and non-nested endpoints. I've found that:

1. if the nested resource has a primary key and you don't have its parent primary key, the nested structure requires you to get it, even though the system doesn't actually require it.

2. nested endpoints typically require redundant endpoints. In other words, you will more often than not, need the additional /employees endpoint so you can get a list of employees across departments. If you have /employees, what exactly does /companies/departments/employees buy you?

3. nesting endpoints don't evolve as nicely. E.g. you might not need to search for employees now but you might later and if you have a nested structure, you have no choice but to add another endpoint. With a non-nested design, you just add more parameters, which is simpler.

4. sometimes a resource could have multiple types of parents. Resulting in multiple endpoints all returning the same resource.

5. redundant endpoints makes the docs harder to write and also makes the api harder to learn.

In short, the non-nested design seems to allow a more flexible and simpler endpoint schema.