一个 API 端点是否基于用户凭据 RESTful 和良好的 URI 设计来区分要返回的资源? [英] Is an API endpoint that differentiates what resources to return based on user credentials RESTful and good URI design?
问题描述
重要提示
这个问题的重点是 API 端点，它区分哪些资源返回取决于谁进行身份验证，例如Alice 得到资源 A 和 B 返回，Bob 得到资源 X 和 Y.
The focus of this question is on API endpoints that differentiate which resources are returned depending who authenticates, e.g. Alice gets resource A and B returned, and Bob gets resource X and Y.
它不是区分返回资源的表示.
It is NOT about differentiating the representation of resources returned.
所有端点都返回资源的 JSON 表示.
All the endpoints return JSON representations of resources.
前言
请考虑以下三个潜在的 API 端点设计，它们都返回用户的 thing 资源.
Please consider the following three potential API endpoint designs, all returning thing resources of a user.
端点 A
GET /things
如果 thing 资源，这些资源与
If authentication credentials for <user_x> are provided with the request, it returns thing resources that specifically relate to <user_x>.
For example, authenticating user Alice gets resource A and B returned, and authenticating user Bob gets resource X and Y.
因此，不同身份验证用户的响应的区别在于返回的是哪些资源实例，而不在于返回这些实例的哪些信息(即资源表示).
So the differentiation of the response for different authenticating users is on which resource instances are returned and NOT on what information of these instances is returned (i.e. the resource representation).
当身份验证失败时，将返回 401 响应.
When authentication fails a 401 response is returned.
端点 B
GET /user/<user_x>/things
端点 C
GET /things/?user_id=<user_x>
端点 B 和端点 C 都提供了与 thing 资源实例，iff认证用户有权访问这些 thing 资源.
Both endpoint B and C provide the thing resource instances related to <user_x>, iff the authenticating user has the right to access these thing resources.
返回的 thing 资源实例的表示，例如返回哪些有关资源的信息，可能会有所不同，具体取决于进行身份验证的用户.例如，
The representation of the thing resource instances returned, e.g. what information about the resources is returned, can vary depending which user authenticates. For instance, <user_x> or an admin user might get back richer data per resource instance then a user with limited access rights.
验证对 thing 资源没有任何访问权限的用户将得到 401 响应.
Authenticating users that don't have any access rights to thing resources of <user_x> will get a 401 response.
我的问题
我想回答以下问题:
1) 端点是 RESTful 吗?
2) 端点 A 的 URI 设计是否良好?
3) 端点 B 和 C 是 RESTful 吗?
4) 端点 B 和 C 是否具有良好的 URI 设计?
我期待您的回答.我还在下面提供了我自己的答案，也非常感谢您对此提供反馈.
I'm looking forward to your answers. I also provided my own answers below and would be grateful for feedback on that as well.
谢谢！
——弗莱迪·斯奈德
推荐答案
更新于 2015 年 3 月 18 日 13:05 CET，在所给出的问题和答案的评论中包含反馈.
UPDATED 18 March 2015 13:05 CET to include feedback in the comments of the question and answers given.
宁静
从纯粹的角度来看，端点都不是 RESTful.例如，该问题没有说明响应是否包含指向资源的链接，以便客户端可以检索资源，而无需了解资源的 URI 是如何构造的.事实上，正如在这篇博文，几乎没有在实践中定义的 API，除了万维网本身，都可以被认为是 RESTful.
From a purist point of view non of the endpoints are RESTful. For instance, the question doesn't state if the responses contain links to the resources such that the client can retrieve the resources without needing knowledge about how the URIs to the resources are constructed. In fact, as pointed out in this blogpost, almost no API defined in practice, other then the World Wide Web itself, can be considered RESTful.
那么关于这些端点有什么好说的吗?我认为有.我们可以讨论处理端点的无状态和幂等性，这对可扩展性很重要.我们可以谈论对安全很重要的端点安全.
So is there nothing useful to say about these endpoints? I think there is. We can talk about statelessness and idem-potency of processing the endpoints, which is important to scalability. And we can talk about safety of endpoints which is important to security.
对于所有端点，您可以声明以下内容:
For all endpoints you could state the following:
它是无状态的吗?
是的，用户身份验证凭据是应用程序状态的一部分，并且随每个请求一起发送，因此服务器处理请求所需知道的一切(无需保持状态)都在请求中.(完整状态转移)
Yes, user authentication credentials are a part of the application state and are send with every request, thus everything the server needs to know to handle the request, without keeping state, is in the request. (The complete state is transferred)
由于这些端点处理 GET 请求，它们是否有效?
端点 A) : 是的，因为对端点 A 的请求，包括用户身份验证凭据，应该被视为一个整体:无论您重复同一请求的频率如何，使用相同的凭据，您将始终获得 <验证用户的代码>事物资源.
Endpoint A) : Yes, because the request to endpoint A, including the user authentication credentials, should be considered as a whole: no matter how often you repeat the same request, with the same credentials, you will always get the thing resources for the authenticating user.
但是，如果您只考虑 URI，则请求实际上不是同上有效的，因为响应会根据提供的凭据而变化.
However, If you only consider the URI, the request is actually not idem potent, because the response changes depending on the credentials provided.
端点 B) 和 C) :与 A) 类似，您将始终获得 URI 中提供的 thing 资源，无论频率如何你重复一遍.
Endpoint B) and C) : Similar to A), you will always get the thing resources of <user_x> provided in the URI, no matter how often your repeat it.
最重要的是，仅考虑 URI 本身，请求也是同上有效的，您需要了解的有关请求的所有信息都在 URI 中，用户凭据只能更改返回的 thing 资源，而不是返回哪些资源.
On top of that the requests are also idem potent only considering the URI itself, everything you need to know about the request is in the URI, the user credentials can only change the representation of the returned thing resources, not which resources are returned.
由于这些端点处理 GET 请求，它们安全吗?
是的，因为请求不会改变任何数据，也不会产生任何其他副作用.
Yes, because the request does not alter any data and does not have any other side effect.
URI 设计
尽管从纯粹的 REST 角度来看，URI 设计被认为是无关紧要的，但在软件开发人员和 API 最终用户使用和处理URI 设计的实际情况中是相关的.
Although from a purist REST perspective URI design is considered irrelevant, in a practical situation where software developers and API end-users use and deal with the URI design is relevant.
端点 A 是否具有良好的 URI 设计?
是和否.当这个 URI 对应用程序用户隐藏，并且不会被添加书签或共享时，这种设计很好.但是，当此 URI 向最终用户公开时，此 URI 设计得不好，因为当将其作为链接共享时，除非她以同一用户身份进行身份验证，否则收件人将看不到相同的数据.
Yes and No. When this URI is hidden from an application user, and this will not be bookmarked or shared this design is fine. However, when this URI is exposed to end-users this URI is not designed well because when sharing this as a link the recipient won't see the same data unless she authenticates as the same user.
端点 B 和 C 是否具有良好的 URI 设计?
是的，最终用户可以从语义上理解端点的含义，并且 URI 可在用户之间共享.
Yes, the end-user can understand semantically what the endpoint is about and the URIs are sharable between users.
因此，您可以选择仅定义端点 B 和 C，而不是定义所有三个端点，因为它们可以提供端点 A 可以提供的所有内容，而且从 URL 可以明显看出所请求的内容.
So, instead of defining all three end points you could chose to only define endpoints B and C because they can provide everything what endpoint A could provide, plus it is obvious from the URL what is requested.
请告诉我你的想法.谢谢！
Please let me know what you think. Thank you!
——弗莱迪·斯奈德
这篇关于一个 API 端点是否基于用户凭据 RESTful 和良好的 URI 设计来区分要返回的资源?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
