php接⼝设计规范,API接⼝设计规范
API整体设计规范
协议
API与客户端通讯协议主要包含http和https，建议使⽤https确保交互数据的传输安全。
域名
主要包含两种形式：
版本控制
版本控制主要⽤于App、⼩程序、软件客户端等与系统不可同时实时更新的情况，来满⾜需要兼容旧版本的场景。
采⽤多版本并存，增量发布的⽅式。
版本号：v{n} n代表版本号，分为整形和浮点型
整型: ⼤功能版本发布形式；具有当前版本状态下的所有API接⼝ ，例如：v1,v2
浮点型：为⼩版本号，只具备补充api的功能，其他api都默认调⽤对应⼤版本号的api 例如：v1.1 v2.2
将版本号放⼊URL中：
这种⽅法⽐较⽅便和直观，版本号主要以整型为主。
将版本号放在请求头(Request Headers)中
headers:{
version: 'v{n}'
...
}
版本号可使⽤整型、浮点型等
路径规则
路径⼜称"终点"(endpoint)，表⽰API的具体⽹址。
在RESTful架构中，每个⽹址代表⼀种资源(resource)，所以⽹址中不能有动词，只能有名词，⽽且所⽤的名词往往与数据库的表格名对应。⼀般来说，数据库中的表都是同种记录的"集合"(collection)，所以API中的名词也应该使⽤复数。
举例来说，有⼀个API提供动物园(zoo)的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下⾯这样。
请求⽅式
对于资源的具体操作类型，由HTTP动词表⽰。影视资源站采集api接口数据
常⽤的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中实践使⽤。
本作品采⽤《CC 协议》，转载必须注明作者和本⽂链接

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。