would be the way to get the employees of a company.
What exactly your employee resource offers would depend on some details of your application. For example you could have logins for admins that are directly related to a specific company. It this case it would be a possible shortcut the employees resource and directly go to an employee or list of employees. But in normal cases /api/employees would only work in combination with companies.
Very interesting question would be the nesting levels. This is one of the questions some people can discuss for hours. Ruby on Rails for example has now an option for "shallow" routes.
While there is no hard technical limit to the number of levels (max length of an URL maybe) I think two levels should be enough for most cases and deeper nesting should be avoided if possible since doing so will make your code better structured and maintainable.
Your example is quite typical and it is easy to show why you would not really need a third level for the tasks in most scenarios. Your tasks are directly related to an employee. So the entity resource somehow already carries the information about the company. (Selecting an employee automatically selects the company). So providing the company in the URL again somehow repeats information.
has all the information necessary to get to your data. So why make it more complex?
I'm not sure if I fully understand your last question.
Restricting access in this context is rather easy. Say you have a client who has only access to resources of the company with id 123. Then all you have to do is to start your controller code by assigning some "hard limits". If the logged in user is not allowed to access anything but one company, then create an obkect for that company and from there on use only this object for any firther access.
Assume we have a Rails projects. For this we have a model for each resource you mention. In addition we have an authentication system in place that gives us the currently logged in user. In this case it would be as easy as this to return something like the list of employees:
Notice that it does not even try to use any company id used in the URL (which in case of Rails would be stored in params[:company_id]).
Try to get the tasks of a specific employee with
Notice again that this is going the "full path" instead of simply using
The first form will create a SQL query with a lot of LEFT JOINS that starts from user, goes through company, employees and tasks. And important in this case: It will fail if a single relation is missing.
Even if not in context of a login and permissions you can still use this to enforce that the user has a certain knowledge about the data. Though in this case you would maybe have to use deeper nested routes. Same example without login but the user making the request must know the correct company id. In this case:
Again go the full way. If your framework does not have this kind of object relations simply nake sure that your SQL requests use JOINS in a similar fashion.