什么是Restful风格的API

 

1、REST的定义

　　请参考论文：https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

2、API文档编写语义：
　　本文档中的关键字：
　　必须-MUST，
　　不得-MUST NOT，
　　必需-REQUIRED，
　　应该-SHALL，
　　不应该-SHALL NOT，
　　应该-SHOULD，
　　不应该-SHOULD NOT，
　　推荐-RECOMMENDED，
　　可能-MAY
　　可选-OPTIONAL

3、请求类型定义
　　请求类型（Method Type）根据业务动作进行合理选择，不能全都使用 POST 方式，如下：
　　PUT：这个请求的含义就是推送某个资源到服务器，更新整个资源
　　PATCH: 更新局部资源
　　POST：向服务器提交一个全新且唯一的资源（无法幂等）
　　DELETE：这个请求会删除服务端的某个资源
　　GET：向服务器获取资源
　　HEAD: 大的语义上和GET请求是类似，只是只需要返回响应头信息即可，通常用于客户端用于资源存在性等判断
　　TRACE：这是一个将服务器所收到请求回显给客户端的请求，主要用于测试或诊断。
　　OPTIONS：返回对于指定资源，可以使用的请求类型。这个方法在正常工作中使用的比较少，它一般用途是，在正式请求资源之前，先看看
对于资源都可以使用那些请求；
　　CONNECT ：请求HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。通常用于SSL加密服务器的链接

4、请求状态码
根据实际业务场景，严格规范定义并正确使用请求状态码，客户端的每一次请求, 服务器端必须给出回应，回应一般包括HTTP状态码 和 数据两部分
　　1xx: 信息，请求收到了，继续处理。
　　2xx: 代表成功. 行为被成功地接收、理解及采纳。
　　3xx: 重定向。
　　4xx: 客户端错误，请求包含语法错误或请求无法实现。
　　5xx: 服务器端错误.
　　2xx 状态码
　　　　200 OK [GET]: 服务器端成功返回用户请求的数据。
　　　　201 CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功。
　　　　202 Accepted 表示一个请求已经进入后台排队(一般是异步任务)。
　　　　204 NO CONTENT -[DELETE]: 用户删除数据成功。
　　4xx 状态码
　　　　400：Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误，服务器不理解客户端的请求，未做任何处理。
　　　　401: Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)。
　　　　403：Forbidden: 表示用户得到授权了，但是访问被禁止了, 也可以理解为不具有访问资源的权限。
　　　　404：Not Found: 所请求的资源不存在，或不可用。
　　　　405：Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
　　　　406：Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式，但是只有XML格式)。
　　　　410：Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的。
　　　　415: Unsupported Media Type: 客户端要求的返回格式不支持，比如，API只能返回JSON格式，但是客户端要求返回XML格式。
　　　　422：Unprocessable Entity: 客户端上传的附件无法处理，导致请求失败。
　　　　429：Too Many Requests: 客户端的请求次数超过限额。
　　5xx 状态码
　　　　500：INTERNAL SERVER ERROR; 服务器发生错误。
　　　　502：网关错误。
　　　　503: Service Unavailable 服务器端当前无法处理请求。
　　　　504：网关超时。

5、REST API的一些设计约束：

　　(1)、统一的设计风格，提供API可读性、适配性，不同开发人员之间可以无障碍通过API可以看到API背后的主干逻辑

　　(2)、单一职责，API设计尽量做一件事情，将能力原子化，后期扩展及对接提升复用性，这也是软件设计原则当中常常需要遵守的

　　(3)、资源封装，API 的设计是对封装好的资源的操作，而不是对数据库的操作

　　(4)、命名规范，合理命名访问地址以及参数，用于降低理解成本

　　(5)、版本控制，确保所有变化，不能影响原有调用方的正常运行，允许在API的URL当中出现版本描述，如： GET /users/v1（代表V1版本的API）

　　(6)、无状态化，API的语义不应该依赖服务端的状态，比如说依赖服务端时钟也不行，查最近1天的人数（比如现在的时间是2024-08-13 18:23:11），那么不能写：GET /users/lastday之类，只能写： GET /users?endTime={时间戳}

　　(7)、资源表述层次分明原则，如/xx业务/xx模块/xx资源，层次分明

　　(8)、API本身是可缓存的

　　(9)、API的URL当中不可以出现动词，而只能出现层次分明的名词

　　(10)、API的URL中使用复数进行命名，如：users

　　(11)、面向公众的服务，建议返回数据格式主JSON，尽管也可以是其它的方式，如XML, CSV等

　　(12）、允许URL当中出现过滤、排序、分页参数，如：GET /users?condition={condition}&sort={sort}&current={current}&size={size}

　　(13)、幂等性原则，除了POST之外，其它的都应该遵守幂等性原则，POST不能遵守是因为POST每次都是创建新的唯一性资源（它无法幂等）

　　(14)、完善的错误状态码描述

      (15)、完善的API文档，最好能够完全符合OAS3.0规范

 

6、REST API的编写示范：

　　(1)、登录：POST /sessions，登录的本质就是创建一个会话

      (2)、退出：DELETE /sessions/{token}，退出登录的本质就是删除一个会话

 　  (3)、注册：POST /registrations，注册的本质就是添加一个注册事件

　　(4)、转账：POST /transactions, 转账的本质就是新增一个交易

　　(5)、查询用户：GET  /users，直接查询用户列表

　　(6)、更新用户信息： PUT /users, 部分更新用户信息

 

7、REST API的最佳实践参考

　　https://www.bacancytechnology.com/blog/rest-api-best-practices

　　https://blog.iclouds.work/2020/09/01/api-design/paypal_api_style_guide