- REST(Representational State Transfer)即表述性状态传递,REST指的是一组架构约束条件和原则。它是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。
- REST就是选择通过使用 http 协议和 uri,利用 client/ server model 对资源进行 CRUD (Create/Read/Update/Delete)增删改查操作。
RESTful
是一种网络应用程序的设计风格和开发方式,基于 HTTP,可以使用 XML 格式定义或 JSON 格式定义。可以通过一套统一的接口为 Web,iOS和Android提供服务
为什么需要Restful ?
- URL具有很强可读性的,具有自描述性
- 规范化请求过程和返回结果
- 资源描述与视图的松耦合
- 可提供OpenAPI,便于第三方系统集成,提高互操作性
- 提供无状态的服务接口,降低复杂度,可提高应用的水平扩展性
Restful 的特点
- 每一个URI代表1种资源;
- 客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源;
- 通过操作资源的表现形式来操作资源;
- 资源的表现形式是XML或者HTML;
- 客户端与服务端之间的交互在请求之间是无状态的,从客户端到服务端的每个请求都必须包含理解请求所必需的信息。
Restful 的优点
- 面向资源,一目了然,具有自解释性。
- 轻量,直接基于http,不再需要任何别的比如消息协议。get/post/put/delete为CRUD操作
- 简单、低耦合
- 数据描述简单,一般以xml,json做数据交换。服务器返回的数据格式,应该尽量使用JSON,避免使用XML。
- 无状态,提高可见性(可以单独考虑每个请求),可靠性(更容易从局部故障中修复),可扩展性(降低了服务器资源使用)
在接口规范方面,我们遵循 Restful 规范,合理的利用 `请求方法`、`状态码` 等来设计 `API`,参考如下:
资源路径 URL
如果当前应用没有把接口数据与静态资源(如图片等)进行分开放置,为了进行区分
接口以 /api
作为前缀,静态资源以 /public
作为前缀。
为了更方便的对接口进行管理以及后续的升级,路径后同时携带当前接口的版本,如:/api/v1/signin
URL具体设计的规范如下:
- 不用大写字母,所有单词使用英文且小写
- 连字符用中杠"-“来提高URI的可读性,而不用下杠”_"
- 正确使用 "/"表示层级关系,URL的层级不要过深,并且越靠前的层级应该相对越稳定
- 结尾不要包含正斜杠分隔符"/"
- URL中不出现动词,用请求方式表示动作
- 资源表示用复数不要用单数
- 不要使用文件扩展名
HTTP动词
对于资源的具体操作类型,由HTTP动词表示(括号里是对应的SQL命令)。
- GET(SELECT):从服务器取出资源(一项或多项)。
- POST(CREATE):在服务器新建一个资源。
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
- PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
- DELETE(DELETE):从服务器删除资源。
过滤信息(Filtering)
如果记录数量很多,服务器不应该都将它们全部返回给用户。此时API应该提供参数,过滤返回结果,比如:
- users?limit=10:指定返回记录的数量
- users?offset=10:指定返回记录的开始位置。
- users?pageNum=2&pageSize=100:指定第几页,以及每页的记录数。
- users?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
- users?animal_type_id=1:指定筛选条件
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /Info/ID/users
与 GET /users?Info_id=ID
的含义是相同的。
状态码(Status Codes)
服务器向用户返回的状态码和提示信息,比如(方括号中是该状态码对应的HTTP动词):
- 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
- 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。