RESTfulAPI编写指南_原创精品文档.pdfVIP

RESTfulAPI编写指南

基于⼀些不错的RESTful开发组件，可以快速的开发出不错的RESTfulAPI，但如果不了解开发规范的、健壮的RESTfulAPI的基本⾯，即便

优秀的RESTful开发组件摆在⾯前，也⽆法很好的理解和使⽤。下⽂Gevin结合⾃⼰的实践经验，整理了从零开始开发RESTfulAPI的核⼼要

点，完善的RESTful开发组件基本都会包含全部或⼤部分要点，对于⽀持不够到位的要点，我们也可以⾃⼰写代码实现。

1.Request和Response

RESTfulAPI的开发和使⽤，⽆⾮是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response）。具有统⼀接⼝的特

点，即，使⽤不同的http⽅法表达不同的⾏为：

GET（SELECT）：从服务器取出资源（⼀项或多项）

POST（CREATE）：在服务器新建⼀个资源

PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）

PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）

DELETE（DELETE）：从服务器删除资源

客户端会基于⽅法向服务器发送获取数据的请求，基于或⽅法向服务器发送更新数据的请求等，服务端在设计API时，也要按

GETPUTPATCH

照相应规范来处理对应的请求，这点现在应该已经成为所有RESTfulAPI的开发者的共识了，⽽且各web框架的request类和response类都很

强⼤，具有合理的默认设置和灵活的定制性，Gevin在这⾥仅准备强调⼀下响应这些request时，常⽤的Response要包含的数据和状态码

（statuscode），不完善的内容，欢迎⼤家补充:

当,和请求成功时，要返回对应的数据，及状态码，即SUCCESS

GETPUTPATCH200

当创建数据成功时，要返回创建的数据，及状态码，即CREATED

POST201

当删除数据成功时，不返回数据，状态码要返回，即NOCONTENT

DELETE204

当不到数据时，状态码要返回，即NOTFOUND

GET404

任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码，即BADREQUEST

400

当API请求需要⽤户认证时，如果request中的认证信息不正确，要返回状态码，即NOTAUTHORIZED

401

当API请求需要验证⽤户权限时，如果当前⽤户⽆相应权限，要返回状态码，即FORBIDDEN

403

最后，关于Request和Response，不要忽略了httpheader中的Content-Type。以json为例，如果API要求客户端发送request时要传⼊json

数据，则服务器端仅做好json数据的获取和解析即可，但如果服务端⽀持多种类型数据的传⼊，如同时⽀持json和form-data，则要根据客户

端发送请求时header中的Content-Type，对不同类型是数据分别实现获取和解析；如果API响应客户端请求后，需要返回json数据，需要在

header中添加Content-Type=application/json。

2.Serialization和Deserialization

Serialization和Deserialization即序列化和反序列化。RESTfulAPI以规范统⼀的格式作为数据的载体，常⽤的格式为或，以json格式