12 | API 风格（上）：如何设计RESTful API？
该思维导图由 AI 生成，仅供参考
RESTful API 介绍
荧光笔
直线
曲线- 深入了解
- 翻译
- 解释
- 总结
RESTful API是一种常用的API风格，基于REST架构风格，通过HTTP协议进行资源的CRUD操作。设计原则包括URI设计、HTTP方法映射、统一的返回格式和API版本管理。URI设计应遵循规范，使用名词复数表示资源集合和单个资源，避免层级过深的URI，并将操作变成资源的属性或嵌套资源。资源操作应映射为HTTP方法，满足安全性和幂等性，且要保持一致性。返回格式应统一，包括成功和失败消息，以减少客户端适配成本。API版本管理是为了满足需求变更和向下兼容的需求，通常版本标识放在URL中。这些设计原则有助于提高API接口的易读性、易用性和一致性。文章还介绍了API命名、统一分页/过滤/排序/搜索功能、域名设置和通过Go快速启动RESTful API服务的示例。RESTful API的核心是规范，资源通过URI标识，使用HTTP方法表示资源的增删改查，返回格式和错误消息应保持一致，支持API版本，并且应该能够向前兼容。此外，RESTful API的查询接口还应该支持分页/过滤/排序/搜索功能，API的域名可以采用不同的格式。整体而言，RESTful API是一种规范化的API风格，通过遵循一系列设计原则，可以提高API接口的易用性和一致性。
《Go 语言项目开发实战》，新⼈⾸单¥68
全部留言(26)
- 最新
- 精选
管清麟我觉得老师可以专门开个gin的专栏，看了一下iam源码写的真好。作者回复: 业界No.1 没有之一
2021-07-01445
h```避免层级过深的 URI。超过 2 层的资源嵌套会很乱，建议将其他资源转化为?参数， 比如： /schools/tsinghua/classes/rooma/students/zhang # 不推荐 /students?school=qinghua&class=rooma # 推荐``` 老师这句话，我想起来了我一个接口，是和用户组相关的。 我有一个组的接口，它本身有自己的增删查改等几个标准的接口 组表和用户表是个多对多关系，我要写三个接口，分别是：显示组用户，添加组用户，删除组用户。 没看这篇文章之前我写成了 get /group/user/:uid post /group/user/:uid delete /group/user/:uid 并且还分别添加了groupid参数，看完老师说的层级过深那段话之后觉得我以前弄的确实有问题，思考之后新的想法如下： 显示组用户应该用 get /group/:gid?fields=user来显示组详情，这里可以通过你说的过滤功能只要显示用户，组其他字段不显示。 添加组用户和删除组用户好像正常情况来讲都是put /group/:gid 就是修改组的那个接口，但是仔细一想，增加用户和删除用户都用 put /group/:gid有点奇怪，而且没办法区分删除还是增加，或者把在后面把现在所有组列出来，比如现在组有用户1,2 增加用户3就是 put /group/:gid?users=1,2,3 ， 假如现在有用户1，2，3，删除3就是 put /group/:gid?users=1,2 其实不止组，很多有外键关系的好像都存在我这个情况，比如作者表和书籍表，作者表和书籍表有自己的增删查改，那如果我要 查看某作者所有书籍，增加作者一本新书，删除作者一本书 其实说了这么多 就是想问下老师 显示组用户，添加组用户，删除组用户这三个例子你觉得该怎么设计接口，能指教一下如果是你会怎么设计这三个接口以及原因吗？作者回复: 显示组用户：GET /groups/:gid 添加组用户：POST /groups/:gid/users/:uid 删除组用户：DELETE /groups/:gid/users?uids=1,2,3 /groups/:gid/users/:uid 这个是其实2层资源嵌套。 这样设计原因是：符合现实世界的分层关系，逻辑更合理
2021-06-297
pedro在过去的经验中，RESTful API对于动词性API不能很好的work，比如说修改密码，重置密码等，很难通过URL和HTTP方法表征出来。 但是对于Github，豆瓣等资源性API，大量的都是资源获取与删除，就特别适合RESTful。作者回复: 是的，可以将这些动词抽象成一个属性
2021-06-2266
return老师，再请教一下, 关于动词性接口 “是的，可以将这些动词抽象成一个属性” 这里 抽象为属性是什么意思。 比如 有一个视频 /video/12345.mp4 , 现在要提供一个 禁播的操作（非删除），该如何操作。 辛苦老师作者回复: /video/12345.mp4?enabled=false 或者： /video/:video/disable
2021-12-233
blackpiglet感觉GraphQL API会比较适合接口变动比较频繁的开发环境，这种API设计看起来基本不用考虑版本兼容的问题，不知道在实际的使用场景中，是不是基于这个原因选择GraphQL，放弃RESTFul的。作者回复: 大体不差
2021-08-022
像RESTful 中 对某个资源的获取 api 中，针对某个特定资源的获取是尽量精简还是需要详细？ 如 需求是 获取最近十条的最新数据 应该是 GET: /data?order=createdAt,desc 还是使用 GET: /last10data 像在 前后端分离的埸景下 是尽量希望不要暴露太多细节给前端好 还是尽量提供更多的参数细节可让前端调用好？作者回复: 选择GET: /data?order=createdAt,desc。 前后端分离的时候，尽量设计的通用些。甚至可以不考虑前端。 前端需要的参数，是接口返回参数的一个子集。
2021-06-2322- Geek_e4ce15一直没有想明白 初期部署的iam到现在有什么用呢 一直是理论也米有涉及到跟iam有关的 除了目录结构
作者回复: 后面会有。 部署的iam只是打通整个编译环境，后面有需要可以自动动手魔改代码
2022-05-22归属地：广东1 
何长杰Atom老师，关于接口的冥等性，一直不太理解其内涵，比如： POST不是冥等的，网上说会N次调用会有N个资源创建，但如果不允许重复也不会创建N个资源。 这里说的资源的状态改变效果该怎么理解？ 还有谈论的冥等的目的是啥？作者回复: 幂等性是指前后两次执行的效果是一样的。 接口幂等性，能提高接口的安全和可重试性。 非幂等性的接口会带来以下问题： 1. 请求失败，再次请求，可能会重复创建资源，这样上一次的资源创建爱你就变成了一个脏数据 2. 以为前后2次执行结果不一样，就导致这个接口失败后，不能重试
2022-04-171- Geek_6bdb4e想问一下如何理解“直接使用 POST 方式来批量删除，body 中传入需要删除的资源列表”这句话呢，我的理解POST是用来资源注册，也就是增删改查中的增，这个是在body中加入待删除的资源列表，然后内部代码处理这个逻辑吗，也就是其实内部是删除的逻辑？
作者回复: 是的。 因为DELETE不能传入多个资源，所以如果是批量删除，需要传入多个资源的时候，可以考虑使用POST，将资源列表放在body中。
2022-03-1821 
无为老师, 有的时候一个请求不只是单纯某一种资源, 还需要一些关联资源, 这个时候怎么处理比较好? 返回结果通过参数有针对性的添加更多的信息?作者回复: 是的，可以这么搞
2022-02-211
