@@ -77,23 +77,23 @@ POST /classes:新建一个班级
7777
7878路径又称"终点"(endpoint),表示 API 的具体网址。实际开发中常见的规范如下:
7979
80- 1 . ** 网址中不能有动词,只能有名词,API 中的名词也应该使用复数。** 因为 REST 中的资源往往和数据库中的表对应,而数据库中的表都是同种记录的"集合"(collection)。如果 API 调用并不涉及资源(如计算,翻译等操作)的话,可以用动词。比如:` GET /calculate?param1=11¶m2=33 ` 。
80+ 1 . ** 网址中不能有动词,只能有名词,API 中的名词也应该使用复数。** 因为 REST 中的资源往往和数据库中的表对应,而数据库中的表都是同种记录的"集合"(collection)。如果 API 调用并不涉及资源(如计算,翻译等操作)的话,可以用动词。比如:` GET /calculate?param1=11¶m2=33 ` 。
81812 . ** 不用大写字母,建议用中杠 - 不用下杠 \_ ** 。比如邀请码写成 ` invitation-code ` 而不是 ~~ invitation_code~~ 。
82- 3 . ** 善用版本化 API** 。当我们的 API 发生了重大改变而不兼容前期版本的时候,我们可以通过 URL 来实现版本化,比如 ` Http ://api.example.com/v1` 、` http://apiv1.example.com ` 。版本不必非要是数字,只是数字用的最多,日期、季节都可以作为版本标识符,项目团队达成共识就可。
82+ 3 . ** 善用版本化 API** 。当我们的 API 发生了重大改变而不兼容前期版本的时候,我们可以通过 URL 来实现版本化,比如 ` http ://api.example.com/v1` 、` http://apiv1.example.com ` 。版本不必非要是数字,只是数字用的最多,日期、季节都可以作为版本标识符,项目团队达成共识就可。
83834 . ** 接口尽量使用名词,避免使用动词。** RESTful API 操作(HTTP Method)的是资源(名词)而不是动作(动词)。
8484
8585Talk is cheap!来举个实际的例子来说明一下吧!现在有这样一个 API 提供班级(class)的信息,还包括班级中的学生和教师的信息,则它的路径应该设计成下面这样。
8686
8787```
8888GET /classes:列出所有班级
8989POST /classes:新建一个班级
90- GET /classes/classId:获取某个指定班级的信息
91- PUT /classes/classId:更新某个指定班级的信息(一般倾向整体更新)
92- PATCH /classes/classId:更新某个指定班级的信息(一般倾向部分更新)
93- DELETE /classes/classId:删除某个班级
94- GET /classes/classId/teachers:列出某个指定班级的所有老师的信息
95- GET /classes/classId/students:列出某个指定班级的所有学生的信息
96- DELETE classes/classId/teachers/ID :删除某个指定班级下的指定的老师的信息
90+ GET /classes/{ classId} :获取某个指定班级的信息
91+ PUT /classes/{ classId} :更新某个指定班级的信息(一般倾向整体更新)
92+ PATCH /classes/{ classId} :更新某个指定班级的信息(一般倾向部分更新)
93+ DELETE /classes/{ classId} :删除某个班级
94+ GET /classes/{ classId} /teachers:列出某个指定班级的所有老师的信息
95+ GET /classes/{ classId} /students:列出某个指定班级的所有学生的信息
96+ DELETE / classes/{ classId} /teachers/{ID} :删除某个指定班级下的指定的老师的信息
9797```
9898
9999反例:
@@ -151,10 +151,10 @@ GET /classes?page=1&size=10 //指定第1页,每页10个数据
151151
152152上面代码表示,文档中有一个 ` link ` 属性,用户读取这个属性就知道下一步该调用什么 API 了。` rel ` 表示这个 API 与当前网址的关系(collection 关系,并给出该 collection 的网址),` href ` 表示 API 的路径,title 表示 API 的标题,` type ` 表示返回类型 ` Hypermedia API ` 的设计被称为[ HATEOAS] ( http://en.wikipedia.org/wiki/HATEOAS ) 。
153153
154- 在 Spring 中有一个叫做 HATEOAS 的 API 库,通过它我们可以更轻松的创建除符合 HATEOAS 设计的 API。相关文章:
154+ 在 Spring 中有一个叫做 HATEOAS 的 API 库,通过它我们可以更轻松的创建出符合 HATEOAS 设计的 API。相关文章:
155155
156- - [ 在 Spring Boot 中使用 HATEOAS] ( a )
157- - [ Building REST services with Spring] ( https://spring.io/guides/tutorials/classmarks / ) (Spring 官网 )
156+ - [ 在 Spring Boot 中使用 HATEOAS] ( https://blog.aisensiy.me/2017/06/04/spring-boot-and-hateoas/ )
157+ - [ Building REST services with Spring] ( https://spring.io/guides/tutorials/rest / ) (Spring 官网 )
158158- [ An Intro to Spring HATEOAS] ( https://www.baeldung.com/spring-hateoas-tutorial )
159159- [ spring-hateoas-examples] ( https://github.com/spring-projects/spring-hateoas-examples/tree/master/hypermedia )
160160- [ Spring HATEOAS] ( https://spring.io/projects/spring-hateoas#learn ) (Spring 官网 )
@@ -163,12 +163,12 @@ GET /classes?page=1&size=10 //指定第1页,每页10个数据
163163
164164- https://RESTfulapi.net/
165165
166- - http ://www.ruanyifeng.com/blog/2014/05/RESTful_api .html
166+ - https ://www.ruanyifeng.com/blog/2014/05/restful_api .html
167167
168168- https://juejin.im/entry/59e460c951882542f578f2f0
169169
170170- https://phauer.com/2016/testing-RESTful-services-java-best-practices/
171171
172172- https://www.seobility.net/en/wiki/REST_API
173173
174- - https://dev.to/duomly/rest-api-vs-graphql-comparison-3j6g
174+ - https://dev.to/duomly/rest-api-vs-graphql-comparison-3j6g
0 commit comments