是区分哪些资源根据用户凭证REST风格和良好的URI设计返回API终点？ [英] Is an API endpoint that differentiates what resources to return based on user credentials RESTful and good URI design?

问题描述

重要提示

这个问题的重点是哪些资源返回根据API端点区分的谁认证的，例如爱丽丝获取资源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.

是不会关于区分资源的重新presentation回来了。

It is NOT about differentiating the representation of resources returned.

所有端点返回资源的JSON重新presentations。

All the endpoints return JSON representations of resources.

preface

请考虑以下三个潜在的API端点设计中，一个用户的所有返回的事情资源。

Please consider the following three potential API endpoint designs, all returning thing resources of a user.

的端点A 的

GET /things

如果对＆LT认证证书; user_x＆GT; 提供的请求，将返回的事情资源的具体涉及＆LT; user_x＆GT; 的。
例如，用户身份验证爱丽丝获取资源A和B回来了，和认证用户Bob得到的资源的X和Y

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.

因此​​，对于不同的认证用户响应的分化上的资源实例返回和不可以对什么是返回这些实例的信息（即资源重新presentation）。

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

的端点ç的

GET /things/?user_id=<user_x>

这两个端点B和C提供的事情有关＆LT 资源实例; user_x＆GT; ，当且仅当的身份验证的用户访问这些的事情的权利资源。

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.

的资源实例返回的的事情，例如重新presentation返回什么关于资源的信息，可以根据该用户认证有所不同。例如，＆LT; user_x＆GT; 或管理员用户可能会得到每资源实例回更丰富的数据，然后用有限访问权限的用户。

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.

鉴定不具有任何访问权限东西的用户的中的资源; user_x＆GT; 将得到401回应。

Authenticating users that don't have any access rights to thing resources of <user_x> will get a 401 response.

我的提问

我想有回答以下几个问题：

I would like to have answers to the following questions:

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.

感谢您！

- 弗雷迪Snijder

— Freddy Snijder

推荐答案

已更新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.

RESTfulness

从视图端点的非一个纯粹一点是REST风格。例如，如果该响应包含链接到资源，使得客户机可以检索该资源，而无需有关的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）：是的，因为请求到端点，包括用户身份验证凭据，应被视为一个整体：无论你如何经常重复同样的要求，具有相同的凭据，你总是会得到的的事情资源验证用户。

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）：到类似），你总是会得到的的事情资源＆LT; user_x＆GT; 中的URI规定，无论多么频繁的重复了。

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的一切，用户证书只能改变返回<$ C重新presentation $ C>的事情的资源，而不是哪些资源被返回。

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的设计？的

Yes和No 。当此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!

- 弗雷迪Snijder

— Freddy Snijder

这篇关于是区分哪些资源根据用户凭证REST风格和良好的URI设计返回API终点？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！