RESTful API接口设计规范

- 一、RESTful的诞生背景
- 二、什么是RESTful？
- 三、Restful API接口设计规范
- - 3.1、协议
  - 3.2、路径规则|域名
  - 3.3、版本控制
  - 3.4、请求类型
  - 3.5、传入参数
  - - 3.5.1、地址栏参数
    - 3.5.2、请求body数据
    - 3.5.3、请求头
  - 3.6、返回格式
- 四、非 Restful Api 的需求
- - 4.1、单例型：
  - 4.2、组合型：
  - 4.3、自定义组合API

一、RESTful的诞生背景

近年来移动互联网的发展，前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…），因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信,于是RESTful诞生了，它可以通过一套统一的接口为 Web，iOS和Android提供服务。
在这里插入图片描述

二、什么是RESTful？

RESTful,简称REST。
1、英文：Representational State Transfer。
2、直译：表现层状态转化。
3、本质：用URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。
4、特点：RESTful是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。 基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。
5、设计原则和约束条件：
5.1、网络上的所有事物都可以被抽象为资源(resource)；
5.2、每一个资源都有唯一的资源标识(resource identifier)，对资源的操作不会改变这些标识；
5.3、所有的操作都是无状态的。
凡事满足这些约束条件和原则的应用程序或设计就是 RESTful。
6、通俗解释：服务器上每一种资源，比如一个文件，一张图片，一部电影，都有对应的唯一的url地址（URI：统一资源标识符），如果我们的客户端需要对服务器上的这个资源进行操作，就需要通过http协议（GET、POST、PUT、PATCH、DELETE）执行相应的动作来操作它，比如进行获取，更新，删除。
7、补充：
7.1、在 RPC 样式的架构中，关注点在于方法，而在 REST 样式的架构中，关注点在于资源 —— 将使用标准方法检索并操作信息片段（使用表示的形式）。资源表示形式在表示形式中使用超链接互联。
7.2、关于http接口、api接口、RPC接口、RMI、webservice、Restful等概念。

三、Restful API接口设计规范

REST描述的是在网络中client和server的一种交互形式；REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）。
下面是根据Restful思想设计的通用规范：

3.1、协议

包含 http 和 https，使用 https 可以确保交互数据的传输安全。

3.2、路径规则|域名

路径又称 “终点”（endpoint），表示 API 的具体网址。
在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的 “集合”（collection），所以 API 中的名词也应该使用复数。
包含两种形式：
a、主域名：
b、子目录：/api/

3.3、版本控制

版本号：v {n} n 代表版本号，分为整形和浮点型
整型：大功能版本发布形式；具有当前版本状态下的所有 API 接口，例如：v1,v2。
浮点型：为小版本号，只具备补充 api 的功能，其他 api 都默认调用对应大版本号的 api 例如：v1.1 v2.2。
放入位置：
1、将版本号放入URL中（方便直观）。
2、将版本号放在请求头。

3.4、请求类型

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

3.5、传入参数

3.5.1、地址栏参数

主要用于过滤查询
a、restful 地址栏参数 /api/v1/product/122 122 为产品编号，获取产品为 122 的信息
b、get 方式的查询字串，此种方式主要用于过滤查询，如下：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序（sequence、order）。
?producy_type=1：指定筛选条件

3.5.2、请求body数据

主要用于提交新建数据

3.5.3、请求头

用于存放请求格式信息、版本号、token 密钥、语言等信息

{
    Accept: 'application/json',     //json格式
    version: 'v1.0'                       //版本号
    Authorization: 'Bearer {access_token}',   //认证token
    language: 'zh'                      //语言
}

3.6、返回格式

默认返回格式：

{
    code: 0,                         //状态码
    msg: 'ok',                       //提示信息
    data: {}                          //主体数据
}

使用 json 格式作为响应格式，状态码分为两种：
a、statusCode: 系统状态码，用于处理响应状态，与 http 状态码保持一致，如：200 表示请求成功，500 表示服务器错误。
b、code：业务状态码，用于处理业务状态，一般 0 标识正常，可根据需求自行设计错误码对照表，参考
在这里插入图片描述

四、非 Restful Api 的需求

我们一般以 Restful Api 作为接口规范，但是由于实际业务开展过程中，可能会出现各种的 api 不是简单的 restful 规范能实现的，因此，需要有一些 api 突破 restful 规范原则。特别是移动互联网的 api 设计，更需要有一些特定的 api 来优化数据请求的交互。

4.1、单例型：

客户端根据需求分别请求对应 Api 接口，在客户端完成组装。
这种模式服务端相对简单，接口复用率高。
每个接口作用单一，如一个 App 首页，可能有轮播图、分类、推荐商品，则需要分别请求：

/api/v1/banners: 轮播
/api/v1/categories: 分类
/api/v1/product?is_recommend=1: 商品

开发过程中可根据实际需要结合使用。

4.2、组合型：

服务端组装数据，然后返回。
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据，如：

api/v1/get-home-data 返回首页用到的所有数据

这类 API 有一个非常不好的地址，只要业务需求变动，这个 api 就需要跟着变更。

4.3、自定义组合API

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级API，具备更高的灵活性，同时又能很容易的实现页面级的API功能。

data:[
    {url:'api1',type:'get',data:{...}},
    {url:'api2',type:'get',data:{...}},
    {url:'api3',type:'get',data:{...}},
    {url:'api4',type:'get',data:{...}}
]

总结：
简单来说就是url地址中只包含名词表示资源，使用http动词表示动作进行操作资源.
下面几个例子：左边是错误的设计，而右边是正确的

GET /blog/getArticles --> GET /blog/Articles  获取所有文章
GET /blog/addArticles --> POST /blog/Articles  添加一篇文章
GET /blog/editArticles --> PUT /blog/Articles  修改一篇文章 
GET /rest/api/deleteArticles?id=1 --> DELETE /blog/Articles/1  删除一篇文章

参考链接：
1、RESTful（百科）
2、网上整理的对于Rest和Restful api的理解
3、什么是RESTful API
4、API 接口设计规范
5、系统API接口规范

秒客网