江苏龙网

  1. 主页 > 生活百科 > >

RESTful API书写规范

RESTful


RESTful API书写规范

文章插图
 
基于一些不错的RESTful开发组件，可以快速的开发出不错的RESTful API，但如果不了解开发规范的、健壮的RESTful API的基本面，即便优秀的RESTful开发组件摆在面前，也无法很好的理解和使用 。下文Gevin结合自己的实践经验，整理了从零开始开发RESTful API的核心要点，完善的RESTful开发组件基本都会包含全部或大部分要点，对于支持不够到位的要点，我们也可以自己写代码实现 。
1. Request 和 ResponseRESTful API的开发和使用，无非是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response） 。本真RESTful架构风格具有统一接口的特点，即，使用不同的http方法表达不同的行为：
  • GET（SELECT）：从服务器取出资源（一项或多项）
  • POST（CREATE）：在服务器新建一个资源
  • PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
  • PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）
  • DELETE（DELETE）：从服务器删除资源
【RESTful API书写规范】客户端会基于GET方法向服务器发送获取数据的请求，基于PUT或PATCH方法向服务器发送更新数据的请求等，服务端在设计API时，也要按照相应规范来处理对应的请求，这点现在应该已经成为所有RESTful API的开发者的共识了，而且各web框架的request类和response类都很强大，具有合理的默认设置和灵活的定制性，Gevin在这里仅准备强调一下响应这些request时，常用的Response要包含的数据和状态码（status code），不完善的内容，欢迎大家补充:
  • 当GET, PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
  • 当POST创建数据成功时，要返回创建的数据，及状态码201，即CREATED
  • 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
  • 当GET 不到数据时，状态码要返回404，即NOT FOUND
  • 任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码 400，即BAD REQUEST
  • 当API 请求需要用户认证时，如果request中的认证信息不正确，要返回状态码 401，即NOT AUTHORIZED
  • 当API 请求需要验证用户权限时，如果当前用户无相应权限，要返回状态码 403，即FORBIDDEN
最后，关于Request 和 Response，不要忽略了http header中的Content-Type 。以json为例，如果API要求客户端发送request时要传入json数据，则服务器端仅做好json数据的获取和解析即可，但如果服务端支持多种类型数据的传入，如同时支持json和form-data，则要根据客户端发送请求时header中的Content-Type，对不同类型是数据分别实现获取和解析；如果API响应客户端请求后，需要返回json数据，需要在header中添加Content-Type=Application/json 。
2. Serialization 和 DeserializationSerialization 和 Deserialization即序列化和反序列化 。RESTful API以规范统一的格式作为数据的载体，常用的格式为json或xml，以json格式为例，当客户端向服务器发请求时，或者服务器相应客户端的请求，向客户端返回数据时，都是传输json格式的文本，而在服务器内部，数据处理时基本不用json格式的字符串，而是native类型的数据，最典型的如类的实例，即对象（object），json仅为服务器和客户端通信时，在网络上传输的数据的格式，服务器和客户端内部，均存在将json转为native类型数据和将native类型数据转为json的需求，其中，将native类型数据转为json即为序列化，将json转为native类型数据即为反序列化 。虽然某些开发语言，如Python，其原生数据类型list和dict能轻易实现序列化和反序列化，但对于复杂的API，内部实现时总会以对象作为数据的载体，因此，确保序列化和反序列化方法的实现，是开发RESTful API最重要的一步准备工作


    推荐阅读


    上一篇：什么是REST？什么是RESTful？

    下一篇：梦见自己老公要和别的女人睡觉 我梦见老公和别的女人睡觉