REST api 可变长度嵌套路径的设计

Question

我需要为嵌套在一个或多个命名空间下的资源设计一个API。

例如：

   / +
     |
     +--- namespace1 
                |
                +-------- namespace2
                             |
                             +---------------- resource

我可能有 0 到 N 个命名空间。

表示此类资源的推荐方式是什么？我考虑过以下方法：

表示URL中的命名空间路径。例如：

GET /resources/namespace1/namespace2/resource

优点：我发现这个最易读
缺点：在 Open API (3.0) 和某些框架 DSL 中仍然存在一些代表此方法的问题。此外，命名空间在“资源”下感觉有些不对劲

将命名空间表示为查询参数：

GET /resources/resource?context=/namespace1/namespace2

优点：易于在 Open API 和 DSL
缺点：在我看来，有点吵

将命名空间表示为 header:

GET /resources/resource
Context: /namespace1/namespace2

优点：易于在 OpenAPI 和 DSL 中声明，比 #2
缺点：不确定我是否喜欢 header

是否有针对此类问题的推荐方法，或者是否有任何我可能遗漏的其他模式？

Answer 1

我同意，#1 是最易读的，如果您使用的技术使其易于使用，则值得考虑。但是，这可能会导致客户端工作以正确形成 API 调用，这不会使 API 特别容易被发现或记录。

#3 实际上只是#2 的变体。您只选择在 header 而不是查询参数中表达名称空间。在任何一种情况下，它都不会使客户端必须 assemble URI，但客户端可能更愿意发送一个“干净”的 URI 请求，而不是添加 headers.

诸如“范围”、“上下文”、“命名空间”和“层次结构”之类的东西都适合作为查询参数。尽管您有所保留，这还是让 #2 变得美味。

这似乎是 KISS 的情况。 REST 没有专门涵盖这种情况。

REST api 可变长度嵌套路径的设计

REST api design for variable length nested paths

rest

api-design