RESTful URL 设计:公共与私有 API、层次化 API 设计模式、URI 与 URL 设计? [英] RESTful URL design: public vs private API, hierhachy API design pattern, URI vs URL design?

问题描述

我经常遇到这样的问题，非常类似于Hierarchical RESTful URL design

I often get into issue like this, very similar to this Hierarchical RESTful URL design

假设该服务仅提供用户上传文档.

Supposed the service only offers the user to upload a document.

POST, GET /accounts
PUT, DELETE /accounts/{name}  or /accounts/{id}

现在一个文档被附加到一个特定的用户，它是否是公开的，这里根本不关心.

Now a document is attached to a specific user, whether it is public or not at all is not of concerned here.

两种方式是POST/documents vs POST/users/documents

为什么?因为稍后创建文档资源时，该文档处于用户的控制之下.所以我希望有

Why? Because later when a document resource is created, that document is under the user's control. So I would expect to have

GET、PUT、DELETE/users/{name}/documents 用于获取、更改和删除用户拥有的一堆文档.

GET, PUT, DELETE /users/{name}/documents for getting, changing and deleting a bunk of documents the users own.

我可以有 GET、PUT、DELETE/users/{name}/documents/{name/id}

但是同样可以通过 /documents/{users}/.... 或/documents/{id} 实现.这类似于组织 unix 文件的方式(尽管 /users/... 也是组织文件的另一种方式...)你看，还有一个哲学[phy of uri vs网址设计.

But the same can be achieved just /documents/{users}/.... or /documents/{id}. And this is similar to how one might organize unix files (though /users/... is also another way to organize files...) You see, there is also a philosophy[phy of uri vs url design.

另一个考虑因素是 API 是否对用户可见.如果这只是一个后端 API，只有开发者可以访问 (backend <-frontend server <-frontend ajax)，那么网站用户可能更喜欢 /users/{name}/documents/{id/name} 而如果API是公开的(比如twitter api)，一些程序员会不喜欢这个长网址.

Another consideration is whether the API is visible to user or not. If this is simply a backend API, only the developer has access (backend <- frontend server <- frontend ajax), then a site user may be happier with /users/{name}/documents/{id/name} while some programmers will dislike this long url if the API is public (like twitter api).

人们如何看待这些问题?

What do people think about these issues?

推荐答案

从实用的角度来说，显然上述所有内容都是正确的.

Pragmatically, obviously all of the above are correct.

但从哲学上讲，我认为这归结为 REST 中的S"……这实际上是一个问题，您正在管理状态的资源实际上是什么.如果您的应用程序旨在处理文档，那么这需要是 URL 中显而易见的资源.如果您的应用更多是关于用户执行某些工作流程，那么您可能希望在 URL 中显示用户.

But philosophically, I think it comes down to the "S" in REST ... This is really a question of what the resource actually is that you are managing state for. If your app is intended to deal with documents, then that needs to be resource that is apparent in the URL. If your app is more about Users performing some workflow, then it is likely that you want to make the User apparent in the URL.

在应用程序内部，为了方便起见，可以快速构建事物，以便您可以拥有混合和匹配资源的 URL，以明确所有权(如您的示例中所示).这么想吧.用户来使用您的应用程序来处理他们的东西，其中一些是文档.他们知道他们登录了，然后他们可以访问他们的文档，他们的一些信息在一个会话中与他们一起传播，从这个角度来看

Internally in an app, things quickly get built for the sake of convenience, so that you can have URLs that mix and match resources to make ownership apparent (as in your example). Think of it this way. Users come to use your app to handle their stuff, some of which are documents. They know they logged in, and then they have access to their documents, some of their information is traveling around with them in a session, and from that perspective

user/{name}/documents

有道理.他们有上下文.

makes sense. They have context.

如果您将该 API 公开……也就是说，如果与您的应用程序中的用户没有相同观点的人正在使用您的 API……那么该公开面孔在语义上需要明确 - 是用户吗?裸露?文件?消费者是否关心谁拥有该文件?该 API 就像一个目录；应该会有帮助.

If you make that API public ... that is, if people who don't have the same perspective as the user in your App are consuming your API ... then that public face needs to be semantically clear - are users exposed? documents? do consumers care who owns that document? That API is like a table of contents; it should be helpful.

因此，如果您的 api 与其他应用程序的合同是您的应用程序公开文档，那么我会说您最好在您的 URL 中明确说明.到用户的路径的概念在这里没有意义，因为上下文与合同无关.

So if your api's contract with other apps is that your app is exposing documents, then I would say that you are better off making that apparent in your URL. The notion of a route to a user doesn't make sense here because the context is not relevant per the contract.

您举了一个有趣的例子，可以清楚地说明这一点.采取

You bring up an interesting example that shows this pretty clearly. Take

document/id 对比 document/name

文件的命名可以遵循约定或特定于应用程序.很好的例子是图像共享应用程序或特定行业(如会计)的应用程序.但是公共 API 不能假设命名约定是显而易见的(除非您允许 API 的使用者访问此类信息).因为它是一个面向公众的 API，所以你最好使用

The naming of files can follow conventions or be app specific. Good example are image sharing apps or apps for particular industries like accounting. But the public API cannot assume that the naming convention is apparent or obvious (unless you allow consumers of the API access to this kind of information). Because it is a public facing API, you are probably better off going with

document/id

因为 id 通常被理解为不可变的，即使在 API 中也是如此，并且语义非常清晰.

because ids are typically understood to be immutable, even across an API and the semantic is pretty clear.

最终，这项技术可以做我们想做的任何事情.但是路由和 URL 之类的东西对于理解 API 本身的语义很重要.如果您正在管理某些东西，那么在使用 API 时这应该是显而易见的，并且不应该被您的本地或技术特定的约定所困扰.

Ultimately, the technology can do anything we want. But things like routes and URLs are important to understand the semantic of the API itself. If you are managing something, that should be obvious when consuming the API, and should not get bogged down by your local or technologically-specific conventions.

这篇关于RESTful URL 设计:公共与私有 API、层次化 API 设计模式、URI 与 URL 设计?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！