RESTful API routes design: nested vs. non-nested

Old post, but not satisfactory answer for me.

It depends on your API. If your data is hierarchical and do not need to access resources without filtering them by their parents, then nested is OK (and not nested too).

If your ids are long (GUIDs), your hierarchy is deep, or you need to access any resource without filtering by its parents then not nested is a good option.

Try to have a unified interface and not having many ways for accessing the same resource.

Try this link that explains this a lot better: https://www.moesif.com/blog/technical/api-design/REST-API-Design-Best-Practices-for-Sub-and-Nested-Resources/

What happens if you want do drill down a couple more levels?

/api/addresses?departmentId=1&employeeId=2&addressId=3

vs

/api/departments/1/employees/2/addresses/3

The Address endpoint suddenly becames bloated with parameters.

Also, if you're looking at the Richardson Maturity Model level 3, RESTful APIs are meant to be discoverable through links. For example, from the top level, say /api/version(/1), you would discover there's a link to the departments. Here's how this could look in a tool like HAL Browser:

"api:department-query": {
  "href": "http://apiname:port/api/departments?pageNumber={pageNumber}&pageSize={pageSize}&sort={sort}"
},
"api:department-by-id": {
  "href": "http://apiname:port/api/departments?departmentId={departmentId}"
}

(either a query that might list them all, in a paged manner eventually, or a parameterized link that would go directly to a specific department, provided you know the id).

The advantage here would be that the client would only need to know the relationship (link) name, while the server would be mostly free to alter the relationship (and resource) url.