RESTful API routes design: nested vs. non-nested

Question

My question is about the advantages of nesting resources when building URLs for API purposes. Consider the following two alternatives for accessing an employee resource:

Answer 1

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.

Answer 2

I'd vote for 2'nd solution, based on model and security.

The department is in the path and does not have to be in the payload, neither for read- or write.

IF depatment of employee is to be changed, the depID could be included in the payload or through separate endpoint (with separate grant) /employees/{ID}.

Answer 3

From my experience: Q1. Easier to use, hard to implement because of relational model Q2. Nested is better when it comes to permissions and others potential checks that you can do before you go levels down