基于REST的API端点设计，滤波和授权 [英] RESTFul API endpoint design with filtering and authorization

问题描述

我设计与消费者具有不同权限的REST API。据我所知，资源的重新presentation应根据用户不会改变。所以我想，以确定哪些是最好的办法：

I am designing a REST API with consumers that have different permissions. I understand that a representation of a resource should not change according to user. Therefore I am trying to determine which is the best approach:

的获取 - 所有文件的清单收集 - 只有管理员的：

/ API /文件

的获取 - 所有文件的清单收集 - 任何用户访问文件123 的

/ API /文件/ 123

/api/documents/123

对于普通用户因此应该端点是

For normal users therefore should the endpoints be

列表中的所有文件中的用户12 的

/ API /用户/ 12 /文件

/api/user/12/documents

的文件123假设用户12访问的

/ API /文件/ 123

/api/documents/123

OR ...应该终点是如下，并使用了查询字符串过滤器：

OR... should the end points be as below and a query string filter used:

/ API /文件？USER = 12

/api/documents?user=12

/ API /文件/ 123

/api/documents/123

推荐答案

在这种情况下，你可以逃脱只需两个端点（和一个头！）。确保为 /文件的API是返回有所不同：授权头。然后你可以使用

In this case you can get away with just two endpoints (and one header!). Make sure the API for /documents is returning the Vary: Authorization header. Then you can use

GET /api/documents              // return all docs the logged-in user can see
GET /api/documents?userId=bob   // return all of bob's docs that the logged-in user can see
GET /api/documents/123          // return doc 123 if the logged-in user can see it    

这也不是完全不合理的鸟巢用户一拉 GET / API /用户/鲍勃/文件。我觉得这是很难为最终用户了解的API有大量的端点，我觉得嵌套的方式往往会造成许多端点。这是概念上更容易转到 /文件，看看你可以过滤的东西，而不是看每个端点，看看过滤它。

It is not entirely unreasonable to nest the user a la GET /api/users/bob/documents. I find it to be harder for end users to learn APIs with a large number of endpoints, and I feel that the nested approach tends to create many endpoints. It's conceptually easier to go to /documents and see what you can filter on, rather than look at each endpoint and see what filters it has.

这篇关于基于REST的API端点设计，滤波和授权的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！