restful api 设计问题请教

[chaleaochexist]

- Root
  - router1
    - category1
        - interface1
          - prefix1
          - prefix2
        - interface2
          - prefix21
    - category2
  - router2
    - category21

上面是结构. api 的设计

1. */api/routers/<router_id>/interfaces
2. */api/interfaces/?router-id=<id> 哪种更好?

如果下一层

1. */api/routers/<router_id>/interfaces/<interface_id>/prefixes
2. */api/prefixes?router_id=1&interface_id=2

谢谢.

[dif]

一般会把参数放在路径里。所以，第一种好一点。下一层也是参数放在路径里。

[iosyyy]

如果有多个建议 2 只有一个建议 1 具体参考 V2EX github 等的设计

[Pil0tXia]

router_id 作为一种资源，出现在路径中或参数中都是符合 RESTful API 的设计规范的。

很多公司会选择同时支持两种用法；你也可以问一问前端同学的喜好，规范一种用法。

通常国外的开发者会倾向于把资源放在路径中，国内的开发者会倾向于把资源放在参数中。这是两种不同的理念，如果这个接口日后的开发迭代会经常变动函数签名，那么把资源放在参数中可能更方便；如果你的资源只有有限的几种，那么把资源放在路径中更合理。

[error451]

按照 restful 规范,很显然是第一种. 参数拼接很显然是不符合的。

当然，实际中，第二种写起来要更灵活一些，你可以随意拼接任何参数。

但是规范的目的本来就不是为了方便，规范是为了统一，让 URL 看起来更加清晰，避免歧义。

比如说，在大家都熟知规范的情况下，你给我*/api/routers/<router_id>/interfaces ， 我不需要查文档就明白，这肯定是一个 interfaces 的列表
并且， 我想获取某个 routers 很显然就是*/api/routers/<router_id>， 我想获取 routers 的列表就是*/api/routers

但是你要给我 */api/interfaces/?router-id=<id> ， 我完全不知道该如何获取 routers 的列表和单个 routers 。

这就是规范的意义，大家都遵守就减少沟通成本。

最后，restful 按理说不要出现复数， 资源写成 router ，interface 就可以了

[hronro]

@error451 说错了吧，Restful 中应该尽量用复数

[lonelee]

作为前端的同学，我更喜欢第一种，第二种如果是 get 请求容易跟参数混在一起

[sx931210]

严格遵守 restful 你不难受谁难受，完全没必要

[shenjinpeng]

可以这样

/api/routers/<router_id>/interfaces

/api/interfaces/<interface_id>/prefixes

[xiangyuecn]

屎山代码：*/api/routers/<router_id>/interfaces

易于封装：*/api/interfaces/?router-id=<id>

[OilMoe]

这很不国内，不应该是全部 POST + get.* 起手吗

[veike]

面向资源设计的 API 资源 ID 肯定放在路径参数中，而不是 query 里

[fancy2020]

我觉得取决于，两种资源之间的逻辑关系，是不是一定是父子的关系。
比如，interfaces 有没有可能独立于 routers 存在？ prefixes 有没有可能独立于 interfaces 存在？

如果答案是，interfaces 是一定会依附在一个 router 上，那么放在 path 里会更好。
如果答案是 interfaces 可以不依附于一个 router ，那么只能放在 query 里。
如果答案是不一定，未来有可能更改，那么放在 query 里会更灵活。

[mingwiki]

不要老是用后端思维，基本的 server rewrite 功能也用上。我觉得一个应用服务一个 api 路由就够了，不同服务让 nginx 、caddy 之类的 rewrite 。
建议用这个 routers<router_id>/api/interfaces
针对不同的服务 rewrite /api/ routers<router_id>/api/