10

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?

Kalyan Chakravarthy S
  • 716
  • 2
  • 7
  • 20

2 Answers2

9

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}
Simon
  • 6,293
  • 2
  • 28
  • 34
1

IMO, both look ok. Use the second one if you want to be able to list all the employees, whatever the department (and filter by departments if necessary).

The first one would make this use case a bit more complicated. Unless you still provide a way to get all the employees using another URI (I would not recommend this though, as being able to find the same information from different URIs make the API hard to understand).

cdelmas
  • 840
  • 8
  • 15