Search code examples
restrestful-architecture

RESTful concepts: organising hierarchical resources

I'm trying to organise REST api for several users types, but I don't understand how resources should be invested in each other. For example, administrator can manipulate with employees list (create, edit and remove items). Also administrator can manipulate list of workplaces for each employee. I think that api routes should be such as:

GET:    /employees
GET:    /employees/{id}
POST:   /employees
PUT:    /employees/{id}
DELETE: /employees/{id}

GET:    /employees/{id}/workplaces
GET:    /employees/{id}/workplaces/{id}
POST:   /employees/{id}/workplaces
PUT:    /employees/{id}/workplaces/{id}
DELETE: /employees/{id}/workplaces/{id}

I know if resource with that id does not exist then I should return 404: Not found, but what about GET: /employees/{id}/workplaces/{id}? Should I return 404: Not found in both cases when employee or workplace with that id does not exist? Or maybe exists other solution for this task?

Another problem is that users with different permissions have different access to resources. For example, Head of Department can get a list of employees of his Department, but can't get a list of other Departments. I propose the following API paths:

GET: /departments/my/employees
GET: /departments/my/employees/{id}

As you can see above, I propose to replace the id on the key word my, which would mean that the id of department must be taken from authorization token. Other users who have more permissions and who can list departments can do something like this:

GET: /departments/{id}/employees
GET: /departments/{id}/employees/{id}

Is this is a true way to build REST service?

Solution

  • what about GET: /employees/{id}/workplaces/{id}? Should I return 404: Not found in both cases when employee or workplace with that id does not exist?

    Yes.

    GET: /departments/my/employees

    If your code can distinguish my from real IDs, this is fine from a REST point of view.