具有关联最佳实践的 RESTful API

Question

我们正在实现一个 RESTful API，我们有 POST 请求，看起来像这样/v1/systems/{systemId}/subsystems和主体看起来像这样{"id": 0, "systemId": 0, "name": "string"} 。 这是变量的重复吗？ 像这样拥有它是一种好习惯吗？

Answer 1

URI 作为一个整体是资源的标识符，而不仅仅是最后一部分。 URI 本身是否遵循某种结构设计也取决于您的设计决策。 像.../systems/{systemId}/subsystems这样的 URI 本身并不一定表明它是systems集合的一部分，其父资源由相应的systemId标识。 只有当客户端自然地探索总共跨越建立这种关系的树的 URI 时，这才会“发展”。 虽然，这种关系通常表达了链接关系想up引用父资源和item为某个特定项目集合中， subsection一个集资源的子部分的等等。 请参阅Iana 的链接关系注册表，看看是否有适合您需要的链接关系。 如果没有可用的链接关系满足您的需要，您可以向 Iana 注册新的链接关系，或者使用Web 链接关系扩展，您可以在其中定义自己的命名空间中的私有关系。

关于在使用 URI 结构时在正文中添加systemId ，其中systemId已在路径中用于标识父资源，那么该信息显然是多余的。 但是，您是否想将它仍然包含在有效载荷中是您的设计选择。 包含或不包含它并没有错。

不幸的是， subsystems资源的信息相当有限。 给定的当前有效负载可能会减少到名称本身，因为systemId在 URI 中给出，子系统资源的id可能是自动生成的，而不是由客户端定义的。 因此，有效载荷将减少为单个名称。 在这里，您还可以避免创建子资源，并通过将子系统名称设计为名称数组来对system条目本身内的子系统名称进行建模。 在这里，您可以简单地为系统资源（通过 Patch）提供一个更新方法来将名称添加到该数组，而不是创建子资源。 但同样，这是您的设计。 任何对你有用的东西在这里都很好。

根据经验，是否在有效负载中包含此类信息，您可以以 Web 为例。 即，如果 ID 应该是呈现给最终用户的表示的一部分，则将其放入。如果不是，则将其省略。 想想你想在页面上呈现的产品。 有时，如果您想为客户提供一种独特的方式来解决该特定产品的问题，那么如果存在相应的 productId 可能会有所帮助。 然而，由于资源标识符不应该尽可能改变，因此将 UUID 公开为内部产品标识符并携带客户应在其他字段中使用的产品标识符可能更有益。 我们的一个客户曾经进行过一次合并，在这次合并中，他们基本上合并了来自两家公司的产品，这些公司的数据库中都有不同的标识符。 结果，即使产品（以它们的真实形式）根本没有改变，他们也不得不修改很多资源 URI。 因此，不幸的是，某些客户突然无法访问以前添加书签的产品说明等，因为没有重定向。 这肯定是一种极端和罕见的情况，尽管它可能会发生，如果您使用的设计支持这种设计更改，那么对整个系统的影响就不会那么显着。

因此，长话短说，这取决于您的设计systemId是否是冗余信息，或者您是否想将该信息添加到有效负载中，或者甚至完全避免使用子资源，而是在父系统本身的列表中携带名称。 这里没有正确或错误的答案。

Answer 2

通常，不会通过 POST 将资源创建到指向单个资源的 URL。 对于 GET、PUT 或 DELETE，您的 URL 看起来更正确。

在不知道您的确切要求的情况下，可以这样做：

POST body {"systemId": 0, "name": "string"} to /v1/systems or /v1/subsystems

响应可以包含创建的子系统以及新的 id。