RESTful URL 设计：公共 API 与私有 API、分层 API 设计模式、URI 与 URL 设计？

我经常遇到这样的问题，与此非常相似分层 RESTful URL 设计 https://stackoverflow.com/questions/7833548/hierarchical-restful-url-design?rq=1

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

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

现在，文档被附加到特定用户，这里不关心它是否公开。

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

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

GET, PUT, DELETE /users/{name}/documents用于获取、更改和删除用户拥有的大量文档。

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

但同样可以实现/documents/{users}/.... or /documents/{id}。这类似于组织 Unix 文件的方式（尽管/users/...也是组织文件的另一种方式...）你看，还有一种哲学[phy of uri vs url design。

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

人们对这些问题有何看法？

实际上，显然以上所有内容都是正确的。

但从哲学上讲，我认为这可以归结为 REST 中的“S”……这实际上是一个关于您管理状态的资源实际上是什么的问题。如果您的应用程序旨在处理文档，那么该资源必须是 URL 中明显的资源。如果您的应用更多的是关于用户执行某些工作流程，那么您可能希望让用户在 URL 中明显可见。

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

user/{name}/documents

说得通。他们有背景。

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

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

你提出了一个有趣的例子，很清楚地表明了这一点。拿

document/id versus document/name

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

document/id

因为 ids 通常被认为是不可变的，即使跨 API 也是如此，而且语义非常清晰。

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