一套设计良好的RESTful一定是前后端反复沟通协商并不断迭代的过程。因为RESTful API作为前后端的桥梁我们需要同时考虑前后端的需求并达成一致的一个结果,桥梁之所以成为桥梁一定是双方都认可的沟通方式。
1、什么是RESTful API
表征性状态传输(Representational State Transfer,简称REST)是Roy Fielding博士于2000年在他的博士论文中提出来的一种软件架构风格。如果一个架构符合REST原则,就称它为RESTful架构。
2、资源(Resources)是REST的核心
REST开发又被称作“面向资源的开发”,这说明对于资源的抽象是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似,是以名词为核心的。这些名词就是资源,任何可命名的抽象概念都可以定义为一个资源。一开始要把产品的RESTful风格定义下来,后面的扩展都可以基于这样的风格延续下去。
3、合理使用URL路径参数和请求
在URL路径里的参数一定是代表某个资源的ID,路径参数也可以是多个代表几级资源的IDs,例如获取一个老师所带班级的详情/teachers/#teacher_id/classes/#class_id。
对于HTTP GET,请求参数一般是作为可选参数获取某个资源列表的子集,例如获取年青老师的列表/teachers?group=young。
对于HTTP POST,请求参数是在消息体里,代表需要新建或者更新的资源。
4、合理使用HTTP响应代码
HTTP响应状态代码,是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分:状态码和原因。两部分都是可定制的,也可以使用标准的状态码,只定制出错原因。在实际应用中也是两种选择:
•一种是对于应用出错的情况扩展状态码,定制出错原因。
•一种是对于容器处理的出错情况默认使用容器返回的错误码,例如tomcat容器返回的503,404;而对于应用本身返回的状态码一律返回200,对于应用出错码和原因都反应在返回消息体中。
5、定义一套标准的返回体数据结构
对于所有的RESTful HTTP请求定义一套标准的返回结构体,前端可以根据这样的固定格式做标准化的解析,对于系统的可维护性起到很大的帮助。这个结构体里应该包含返回的具体资源,结果状态码和错误原因(如果有的话)。对于返回的资源,数据类型也尽量做到统一,比如日期,枚举类型都返回统一的数据类型避免不同的API对同一种数据有不同的处理方式。资源属性尽量做到可读也能大大减少前后端的沟通成本。
6、RESTful API的版本控制
一个简单的做法是直接在URL中插入版本号,这样可以允许多个版本的API同时运行。在已经发布的版本中尽量做到向后兼容,包括URL和参数,对于返回值也是尽量增加新的冗余参数以兼容不同客户端不同的升级频率。等到所有的客户端升级以后再去除冗余的过程。
http://km.ui.tedu.cn/news/178488.html