使用REST API来查找依赖于上下文的列表

Question

I am currently trying to decide on the best approach to solve a problem I am having with designing my REST API.

The simplified scenario is my web application has two resources for example departments and employees. Both are security controlled within the business layer.

A user can exist who has access to employee but not to department, however when this user edits an employee they need to be able to select that employee's department from a drop down list (similarly they might have a list of employees that they want to filter by department).

Ordinarily that user would not have access to the department object so wouldn't be able to call /department/ for example but in the case of editing an employee they need the list of departments.

What would be the recommended way of dealing with this, would I return a list of departments on each GET of /employee/ or would I create another resource which was a combination of employee and department objects (department being the full list of departments)?

I can't currently change the security on the objects as this is deeply ingrained in the application logic.

Has anybody got any ideas?

Regards, Gary

Answer 1

创建一个名为“ DepartmentList”的新资源

Answer 2

Note : I think plural names are better.

You have to think of what would make the life of your users (devs) easier.

A combined resource would 'pollute' your api. Your api would expose /employees, /departments and /employeeDepartments. I don't think the latter deserves to be that high in the hierarchy.

It'd be also be a little more complex for your users to use:

"To edit an employee you need to set a department, BUT that department is not always available at /department, so you better get it from employeeDepartments ... "

Think of your employee object: GET /employees/123

 employee:{
    name: John,
    ... 
    department: {
        id: ID
        --a subset of data--
    }
}

The subset of data should be enough to operate for Users with no rights, and Users with right access may operate on /departments/ID.

Now, how to get the list of available options?

I use to provide a 'special' action /new where I provide a 'form' which users can use as a template to post and create a new resource. This is not an adopted Rest 'standard' but is HATEOAS friendly - it really helps to the discoverability of your api.

So, GET /employees/new could print

 employee:{
    name: "",
    ... 
    department: [{ id: 1, --subset of data-- },{ id: 2, --subset of data-- }.. ]
}

There is some convention to be taken on the format (eg: user needs to know that it only has to pick one department). But that's a hole new discussion.