Api设计指南

基本概念

应用程序编程接口

按层级划分

操作系统->编程语言->框架类库->Web API

编程语言对操作系统的API封装,框架类库对编程语言API的封装, Web API是对框架类库的封装

按通讯方式划分

RPCREST APIWebSocket API
消息格式二进制Thrift,Protobuf,GRPC文本XML,JSON,GraphQL 二级制,文本json
通讯协议TCPHTTP,HTTP/2HTTP,websocket
性能一般 一般
接口契约IDLThrift,Protobuf IDLSwaggerSwagger
客户端强类型客户端HTTP客户端websocket客户端
框架Dubbo,GPRC,Thriftweb框架websocket框架
开发者友好一般自动生成存根、客户端、使用友好,二进制消息阅读不友好json可读性高,通用性json可读性高,通用性
应用场景服务间通讯推荐PRC对外暴露接口推荐REST大文件类的流式数据,语言识别服务

既然有HTTP协议,为什么还要有RPC

按应用场景划分

业务应用

app,小程序,pc站,手机站 等客户端提供 api

开放平台(Open API)

PaaSSaaS Serverless 平台的服务API

API设计必须要具备的指标

规范和风格

restful api 风格,laravel框架自带

Restful Api 风格规范研究

github路由风格,https://api.github.com/

全部小写,多单词时用短划线分隔

http://xxxx/register-phone

不要用下划线,下划线的域名和路由在一些第三方开放平台无法通过验证,如qq互联申请时

鉴权

OAuth2

Laravel搭建OAuth2.0服务

LaravelSanctum 授权 SPA场景

防止重放攻击

请求限流

浅谈api限流

按时间限流,req/minute

随机拒绝,如秒杀场景

api(路由)版本管理

Laravel路由版本控制的实现。

Restful Api 风格规范研究

状态码用http status code 还是 在response body 中自定义code

列举总结一下各大厂的API的设计风格

总结

  • 国内资讯类大厂出于兼容性考虑 以及杀毒软件和安全浏览器 拦截404 页面 等并未采用REST API
  • 业务复杂度高的开放平台也未采用Rest API 如支付宝,微信,微博
  • 国外API多采用REST API 包括很多框架的设计(PHP Laravel)

百度手机站

jsonp http status code 200

百度PC站

jsonp ,收集搜索数据接口 http status code 200

今日头条PC

json,使用message区分状态 http status code 200

今日头条手机站

json http status code 200 has_more 区分

新浪微博PC

json http status code 200 直接返回html

微博手机站

Google手机站

restful api

极光推送

RestFul API HTTP STATUS CODE + Response Body 自定义CODE

GitHub

Restful API https://developer.github.com/v3/#client-errors

个人结论

遵守RFC规范,遵守业内标准,融入生态,工业技术是要标准化的。

更详细的论述看左耳朵耗子的文章 “一把梭: REST API 全用 POST”

应用案例

laravel框架默认的错误信息返回风格

去掉最外层data数据包裹 文档

参考