API整体设计规范

协议

API与客户端通讯协议主要包含http和https，建议使用https确保交互数据的传输安全。

域名

主要包含两种形式：

1. 主域名：https://api.example.com
2. 子目录：https://example.org/api/

版本控制

版本控制主要用于App、微信小程序、软件客户端等与系统不可同时实时更新的情况，来满足需要兼容旧版本的场景。
采用多版本并存，增量发布的方式。

版本号：v{n} n代表版本号,分为整形和浮点型
整型: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2
浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

1. 将版本号放入URL中：
   https://api.example.com/v{n}/
   这种方法比较方便和直观，版本号主要以整型为主。

2. 将版本号放在请求头（Request Headers）中

   headers:{
       version: 'v{n}'
       ...
   }

   版本号可使用整型、浮点型等

路径规则

路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

请求方式

对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

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

例如：

GET /product：列出所有商品
POST /product：新建一个商品
GET /product/ID：获取某个指定商品的信息
PUT /product/ID：更新某个指定商品的信息
DELETE /product/ID：删除某个商品
GET /product/ID/purchase ：列出某个指定商品的所有投资者
GET /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

传入参数

传入参数分为3中类型

1. 地址栏参数

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

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

2. 请求body数据

主要用于提交新建数据等

3.请求头

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

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

返回格式

默认返回格式：

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

使用json格式作为响应格式，状态码分为两种：

• statusCode: 系统状态码，用于处理响应状态，与http状态码保持一致，如：200表示请求成功，500表示服务器错误。
• code：业务状态码，用于处理业务状态，一般0标识正常，可根据需求自行设计错误码对照表，参考
  

非Restful Api的需求

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

组合型：

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

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

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

单例型：

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

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

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

todo

Laravel中实践使用。

参考：https://github.com/mishe/blog/issues/129

本作品采用《CC 协议》，转载必须注明作者和本文链接