Web API 设计 笔记

• Web服务器的概念 从单个计算机 变成了 全球云端基础设施中 一个完全虚拟的部分。

• Web客户端 从传统的安装了浏览器的桌面个人电脑 变成了 无数可以感知物理世界，并与之交互的设备，这些设备通过云端的Web服务器与其他设备相连。

• 服务器端和客户端之间的交互方式也发生了巨大变化。

  • 过去，Web服务器提供HTML，由客户端展示为Web页面；
  • 类似的，Web客户端将HTML表单提交给服务器处理。
  • 这种交互模式主要使用GET和POST,只用到了HTTP的一部分功能。
    • HTTP还定义了PUT DELETE PATCH 方法。

利用 Web API, Web 服务器可以提供完整的HTTP应用程序模型，支持对资源的编程访问。

• HTML5 和 移动应用 是Web API的助推器。

任何Web API都必将发生改变

• 同时支持新旧版本
• 要灵活，可演化
  • 将Web API和超媒体结合。这是一个激动人心的新方向
  • 客户端不再有固定的操作流程，而是根据可用的链接修改自己的行为，以进行演化

创建一个使用HTTP进行通信的API非常简单，而挑战在第一个版本部署后才会出现。

• 媒体类型和超媒体 就是设计可演化API的核心
• HTTP协议的制定者对这个问题进行了周详的考虑
• 很多API开发者并未对此加以考虑或利用
  • 部署的API没有合理使用HTTP协议
  • 客户端严重依赖API的具体实现
  • 这样的API很难演化，极易破坏客户端功能

历史

因特网

• 1960前后，Arpanet在美国大学和实验室共享数据
• 1982年 Arpanet衍生出全球性网络 因特网——全球开放系统
• 它建立在一组通信协议的基础上（Internet protocol suite 因特网协议族）
• 这组通信协议是TCP/IP

万维网

• 1989 欧洲 Web(World Wide Web)一个新系统 名叫万维网
• 可以用来通过 Web浏览器 访问 因特网 上连接的文档
• Web文档大多用HTML书写
• 浏览这些文档需要一个特殊的 应用协议：HTTP

HTTP协议是网站运行和Web API工作的核心。

Web的体系结构

Web的三个核心概念：

1. 资源
2. URI (统一资源标识符)
3. 表示 （representation）

资源

1. 资源的范畴：

任何带有URI标识的东西 都是资源

• 资源不限于是文件
• 资源可以是一个可建立连接的服务
• 还可以是一个流媒体
  • 视频流
  • 音频流

2. 资源必须关联数据库吗？

误解：资源必须对应到一个有数据库支持的实体或者业务对象

• Web API没有这样的限制

3. 媒体类型（mediatype）

从资源返回数据的格式

• application/json

URI

一个URI只能对应一个资源，多个URI可以指向同一个资源

1. URI的格式 scheme:hierarchical part[?query][#fragment]

• http://../../..
• http://..
• mailto:..@...com
• telnet://xx.xx.xx.xx
• urn:isbn:xx-xx-xx-xx

hierarchical part 可以包含 安全证书颁发机构 和 分层路径

2. URI分两种类型: URL 和 URN

• URN只标识，不包含如何获取
• URL标识 同时指定了访问该资源的方法

3. 要不要在URI中使用查询字符串？

有些缓存会自动忽略任何带有查询字符串的URI

也就是

所有带查询字符串的URI请求 都会转到源服务器进行处理

这会对系统扩展产生重要影响

有人倾向于不适用查询字符串，而把这部分信息 放在URI路径中

静态资源不要使用查询字符串，以便缓存

4. 酷URI

简单易记 不变 的URI

• 例如 www.example.com/people/alic…
• 如果 你希望客户端保存只想你的资源的书签，那么就应该考虑使用酷URI
• 不是所有的情况下都要用酷URI
• 不必用很多酷URI也可以把API设计的很好
• Cool URIs for the Semantic Web (w3.org)

5. 表示

资源在某个时刻 状态的快照