WEB-API 的设计与开发

Web-API 简介：

• 通过 HTTP 协议进行网络调用的 API

• Web 系统，通过 URI 完成信息交互

• 开放 API：使自己公司的服务、数据公布与互联网 Amazon:公开 API 使其他网站可以销售其商品 Twitter：早在 2006 年就开始公开 API

场景：

• 已发布的 web 在线服务的数据、功能通过 API 公开（需考虑：风险、所得）

• 将附加在其他网页的小组件公开

• 构建现代 WEB 应用

• 开发智能手机应用

• 开发手机社交游戏

• 公司内部的多个系统集成

问题：

• 无所适从

• 凭经验、模仿

• 缺乏章法

• 认识比较偏感性，口口相传

• 很多人只认为返回 JSON 数据的 URI 才是 API，实际上 Web 系统中的 URI 都是 API

让 API 优雅的理由：

• 易于使用

• 便于更改

• 健壮性好

• 不怕公之于众

• 怎样美化：设计遵守已有规范，遵守事实标准， REST风格
  

设计规范：

请求 URI 设计的基本思路：

• 容易记忆的 URI，包含功能一目了然

• 短小便于输入

• 易读易懂

• 没有大小写混用

• 修改方便

• 不会暴露服务架构

• 规则统一

按照 HTTP 协议的请求方法类型规范使用：

• GET：获取资源

• POST：新增资源

• PUT：更新已有资源

• DELETE：删除资源

• PATCH：更新部分资源

• HEAD：获取资源的元信息

我所见的 HTTP-API 中，大部分都只有 POST、GET 请求。

资源访问性 URI 设计注意：

• 使用名词的复数形式

• 注意所用单词（search 场所/find 东西）

• 不使用需要编码的字符及空格

• 使用连字符分割单词
  

• API 的各种样例参考： https://www.programmableweb.com/
  

国际大厂的设计案例：

分页的几种方式：

• 使用相对位置 offset：（当数据量比较大时，效率会降低）

• 使用绝对位置 max_id

• hasNext

响应数据的格式：

• JSON

• XML

• PHPserialize

• …

对于多格式支持，可使用查询参数指定，使用扩展名方式指定，使用在请求头部指定媒体类型，比如 Content-Type：application/json

目前 JSON 这种数据格式已经占据了大部分 API 的数据格式。

最大程度的使用 HTTP 协议：

• 了解基准协议，私有协议，避免引入私有协议

• 正确使用状态码：尽可能使用 HTTP 协议规范的状态码，不用私有定制状态码。

• 缓存 Expires:RFC 7234 Cache-Control 

• 媒体类型

• 同源策略与跨域问题（jsonP,CORS）

维护与更改：

• 通过版本信息来管理 API(指定版本参数、URI 嵌入版本)

• 尽可能向下兼容

• 区分移动端与 web 的差异

• 变更信息公布

• 停服规范

API 常见安全问题：

数据的非法获取：

• HTTPS 加密：HTTPS 加密不能完全保证安全。

• 中间人攻击：证书获取服务伪造，证书需要设置合理的有效期。

• 公共 WIFI

• 客户端的安全系数：客户端如果本身存在安全问题，那通讯与服务端做的再好也白搭。

浏览器访问的 API 所存在的问题：

• XSS：跨站点脚本攻击

• XSRF：跨站点请求伪造

• JSON 劫持

• 参数篡改：通过参数猜测，进行越权访问

• 多次请求：通过多次调用达到同一功能的多次执行，比如转账，发放优惠券。

• 拒绝服务攻击（DoS）：使用一些手段将流量带宽打满，使正确的访问无法进入。

本文整理于读书笔记：《 web-api设计与开发》一书：

这本书通过列举大量一线互联网公司的开放 API 实例，讲解了 API 设计的方方面面，对于笔者本人来说，虽然很多内容平常开发有涉及，还是有所受用，提升了对 API 重要性的认识，以及设计时的一些策略。

再者就是，书中强调开发这需要注重使用现有权威组织既定的规范、协议，而非自己自定义规范协议，让开发的 API 更利于理解，使用更方便。

有哪些让你想吐槽的糟糕的 API 设计，在评论区写下你的感受和建议！