Using a sub-resource or not?

Question

Take the following example:

We want to infer company and employee information from the RESTful API.

Company data should be quite simple:

GET api/v1/companies GET api/v1/companies/{id} 

Employees GET companies, but we still want to get them separately, so the best solution:

Solution 1: Using Sub-Resources

Get all employees for the company:

 GET api/v1/companies/{companyId}/employees 

Get a specific employee:

 GET api/v1/companies/{companyId}/employees/{employeeId} 

Solution 2. Use of independent resources

Get all employees for the company:

 GET api/v1/employees?companyId={companyId} 

Get a specific employee:

 GET api/v1/employees/{employeeId} 

Both options seem to have their pros and cons.

• With sub-resources, CompanyId may not always be available to me when you want to get an individual employee.

• With an independent resource, so that all employees of the company should use a sub-resource approach if we want to be RESTful.

Otherwise, we could use a mix, but this does not match the sequence:

Get all employees for the company:

 GET api/v1/companies/{companyId}/employees 

Get a specific employee:

 GET api/v1/employees/{employeeId} 

What is the best approach to this situation if we want to stay true to RESTful standards?

Answer 1

For me, this sounds like a common many-to-many relationship problem for RESTful services. (see How to handle many-to-many relationships in the RESTful API? )

Your first solution seems good at first, but you will have problems when you want to access the relationship itself.

Instead of returning an employee with the following GET request, you should return the relation.

GET api / v1 / companies / {companyId} / employees / {employeeId}

If the relationship can be identified with 2 keys, this solution seems perfect. But what happens if a relationship is identified using a 3+ id? URI is getting pretty long.

GET api / v1 / companies / {companyId} / employees / {employeeId} / categories / {categoryId}

In this case, I would come up with a separate resource for the relationship:

GET api / v1 / company-employees / {id}

The returned model in JSON will look like this:

 { "id": 1 <- the id of the relation "company": { "id": 2 }, "employee": { "id": 3 }, "category": { "id": 4 } } 

Answer 2

I think it would be good to provide both. If you want the client to first look at the list of companies, then select a company, and then get a list of all employees, the first approach is necessary. If, perhaps, you also want the client to be able to filter employees by name or age, but without knowing the company identifier, you should also provide a second approach. It depends on what you want the client to do. In my opinion, there is no need to provide a second approach if customers can filter employees only by company ID.

Answer 3

I would go for the first approach and provide some links for getting a subordinate resource.

If I take an example of a new employee that you can add to the company. This seems to be tricky, as the client with the second approach does POST in their collections. What for? Because he must know the company identifier, which is "somewhere else." At the first approach, when you followed the path, you already know this information (companyId) ... so it’s easier for the client to add a new employee.

Back to your example. The main advantage of the second approach is that if your client wants something like "the number of employees in the city", where you are not interested in the concept of a company. But it looks like you need a company concept, so I would go first.

Also, very related to this question: RESTful design: when to use sub-resources?