Rest URL Standards - Multiple Path Parameters

Question

We are building a restful service for serving employee data.

We have an api which will return the list of employees who belong to a specific department of a client.

This api takes 2 parameters - clientId and departmentId

As per standards which of the below is the right way to construct a restful url for this api?

1) /client/{clientId}/department/{departmentId}/employees

2) /client/{clientId}/employees?departmentId={departmentId}

Can a restful url can have multiple path parameters? If yes/no to above question - why it is so?

Answer 1

In RESTful APIs the path parameters are used to identify a resource (client, order, blog post etc). This resource is often a record in some database. Some database tables have composite keys e.g if you have a system that stores data about the employees of several different clients then there might be entries in your database like

name | client_id | department_id
John |    1      |      1
Jane |    2      |      1

Where both clients have a department with id 1.

In that case if the purpose is to identify the resource of list of all employees in a given department for a given client then it makes sense to use several path parameters.

 /client/{clientId}/department/{departmentId}/employees

However if this is more of a search API then it might make sense to have

employees?age={age}&height={height}