首页 文章

针对具有单个 endpoints 的多个响应的RESTful设计

提问于
浏览 次
2

我正在开发提供REST API的项目 . 最近，我们决定将其与Swagger集成，为每个 endpoints 创建详细的文档 . 几乎所有的REST都已成功集成，但对于其中一些我们遇到的困难很少 .

因此，我们有一个带有“/ users”资源的REST，它默认按照JSON格式的给定标准返回用户列表，例如： ：

[
{
    name: "user1",
    age: 50,
    group: "group1"
},
{
    name: "user2",
    age: 30,
    group: "group2"
},
{
    name: "user3",
    age: 20,
    group: "group1"
}
]

此REST的一个要求是按“ group ”字段对用户进行分组，并提供以下格式的响应：

[
    group1: [ 
        {
            name: "user1",
            age: 50,
            group: "group1"
        },
        {
            name: "user3",
            age: 20,
            group: "group1"
        }]
    group2: [
        {
            name: "user2",
            age: 30,
            group: "group2"
         }
    ]
]

当查询参数 groupby 等于"group"时，我们提供此类响应 . 因此，问题在于Swagger允许通过单个 endpoints （方法和响应代码）仅提供单一响应格式 . 例如 . 我们无法为 /users endpoints “ 200 ”响应代码和 GET HTTP方法提供2种响应格式 .

而现在我对如何改变我们的REST设计以使其与Swagger兼容的方式感到困惑 .

Notes: 根据REST设计原则，为组合用户添加新 endpoints 似乎不正确 grouped users 不是单独的资源，而只是现有资源的附加表示 .

Swagger并不是一个严格的要求，因此任何有关其他REST文档工具的想法都将受到高度赞赏

rest design swagger design-principles

1 回答

  • 5

    正如您正确指出的那样，在两个用例中返回两种不同的格式（表示） . 未分组用户作为用户的数组（集合）返回 . 当您追加 groupBy 查询参数时，您将返回完全不同的内容 - 一组 search results .

    如果要进行RESTful搜索，请将搜索视为自己的资源 . 缺点是它需要向服务器发出两个请求才能获得响应：一个用于创建 search 对象并返回201，其中包含相应的 Location 标头和搜索结果的链接，另一个请求检索此搜索的结果 . 好处是，它将与Swagger一起使用，您可以重用其他资源的模式 .

    或者，如果您只需要通过一个参数 - 组对用户进行分组，您确实可以添加额外的资源： /user-groups ，因为您正在有效地检索嵌入了用户集合的 all 用户组 .

    回复于

相关问题