飞利浦 Hue 智能照明系统开发（Part 1 - API 入门）

我家里有超过 10 个的飞利浦 Hue 智能灯泡，我通常使用 Amazon Echo 和 iOS HomeKit 控制它们，例如说睡觉时对着 Echo 喊「Alexa, turn off bedroom.」，或者在 iPhone 上通过 Control Center 迅速开关一盏灯。在我买了一个 Raspberry Pi 架设加密 DNS 后，我就开始思考是否能在 Raspberry Pi 上跑一个程序控制 Hue 做更复杂的事情。在此之前，我先要自己搞明白 Hue 的 API 是如何工作的以及能做什么，于是我开始阅读 Hue API 文档。

Hue API 是很典型的 REST API，我们可以通过 bridge 上面的 HTTP 服务器调用 Hue API 操作这个 bridge 连接的所有灯泡。Hue API 可以操作的对象包括灯泡、房间、传感器、规则等等，不过在我们能够调用这些 API 之前，首先我们必须找到 bridge 的 IP，然后才能连上它的 HTTP 服务器。

寻找 Hue Bridge

大多数人家里的网络都是用 DHCP 动态分配 IP，因此我们不知道 Hue bridge 的 IP 是什么，就算知道了将来还可能变。我们要如何连接 bridge 呢？最简单的方法是发一个请求到这个地址：

https://www.meethue.com/api/nupnp

这是飞利浦自己的服务器，不是我们家里 bridge 的服务器。它会根据我们的公网 IP 来查询我们家是否有 bridge 通过同一个公网 IP 连接着飞利浦的服务器，如果有的话它就会返回这个（或这些）bridge 的信息，包括内网 IP。例如说：

[
  {
    "id": "001788fffe000999",
    "internalipaddress": "10.0.0.9"
  }
]

这个 JSON 里面只有一个 bridge，这也是最常见的状况。（很少人会需要在家里装超过一个 bridge。）这一个 bridge 的 IP 是 10.0.0.9，也就是 internalipaddress 属性的值。那 id 属性的值是什么呢？这是这个 bridge 的序列号，如果这个 bridge 的 IP 将来发生了变化，我们可以通过这个序列号来确认这是同一个 bridge。

在找到 bridge 的 IP 后，我们就可以连接上去了。我这里提到的只是最容易上手的 bridge 寻找办法，更复杂的方法可以看官方的 Hue Bridge Discovery Guide。

Hue Bridge 本地授权

能够连接到 bridge 的 IP 并不意味着能够操作 bridge，否则 bridge 就没有任何安全性可言了。任何新的客户端连接 bridge 之前，都需要有人去手动按一下 bridge 上面的物理按钮，然后新的客户端才能获取到授权。

首先，我们要按下 bridge 上的物理按钮，然后发送一个 POST 请求到这个地址：

http://<bridge_ip>/api

这个 POST 请求需要带上一个简单的 JSON：

{
  "devicetype": "<app_name>#<device_name>"
}

这个 JSON 只有一个叫做 devicetype 的属性，用来命名这个新增的客户端，格式为应用名称加上 # 再加上设备名称。（一个应用可以安装在多台设备上，这样的命名格式要求可以帮助区分。）官方文档说这个字符串长度不能超过 40 个字符，其中应用名称不超过 19 个字符，设备名称不超过 20 个字符。实际上当前的 API 版本（1.24.0）只检查字符串长度是否超过 40，不检查应用名称和设备名称是否超过允许长度。

这个请求成功的话，返回的 JSON 会是这样子的：

[
  {
    "success": {
      "username": "83b7780291a6ceffbe0bd049104df"
    }
  }
]

我们获取到了一个叫做 username 的东西，这实际上是个密钥一样的东西，因为只要掌握了它就能操作 bridge。我们需要把这个密钥保存下来，然后我们就可以进行其他任意操作了。

测试请求

拿到 username 后，我们当然要测试一下能不能用。Hue API 传输 username 这个密钥的方式很有趣，我们需要把它放在 URL 里面，例如这样子：

http://<bridge_ip>/api/<username>/config

发一个 GET 请求到这个地址，我们就能获得这个 bridge 的所有配置信息。成功获取信息意味着 username 是有效的密钥，之后我们就能用它来获取其他信息了。以下是一些可以尝试 GET 请求获取的地址：

http://<bridge_ip>/api/<username>/lights
http://<bridge_ip>/api/<username>/groups
http://<bridge_ip>/api/<username>/schedules
http://<bridge_ip>/api/<username>/scenes
http://<bridge_ip>/api/<username>/sensors
http://<bridge_ip>/api/<username>/rules
http://<bridge_ip>/api/<username>/resourcelinks
http://<bridge_ip>/api/<username>/capabilities

总结

拥有上述知识后，我们就可以进一步探索 Hue API 了。为了方便方便我自己，我写了一个叫做 Hue Explorer 的开源项目用于连接我自己的 bridge 并查看上面的信息，如果你想要看源代码的话你可以到 GitHub 上查看。我暂时只做了一部分的 JSON 可视化，例如说灯可以可视化为这样子：

如果你想要用第三方工具发送 REST 请求，可以试一下免费的 Postman。如果你懒得下载，可以直接访问 http://<bridge_ip>/debug/clip.html，这是一个每一个 bridge 都自带的调试工具，可以用来手工编写 REST 请求。

在下一篇文章里，我会开始讲述每一个具体的 Hue API 能做什么，不想错过的话欢迎通过邮件或 RSS/Atom 订阅我的博客。

怎么样才算是 RESTful？读 REST in Practice

最近 O’Reilly 搞活动，我就半价买了一本《REST in Practice》（Kindle 版链接）。对于 O’Reilly 的书，我通常会对比 O’Reilly 打折后的价钱和 Kindle 版的价格，通常是那家更便宜就在那家买，但图表或代码比较多的我就会坚持买 O’Reilly 的版本，因为 PDF 能够最好地保存这些格式。

回到 REST 的话题上。尽管这个概念 2000 年就被提出来了，2007 年成为了一个热词，随后越来越多的服务都宣称自己是 RESTful 的，但是到底真么做才是真正的 REST 我从来没有自习学习过。由于 2007 年的时候 Ruby on Rails 也十分热门，所以我以为 Rails 风格的 CRUD API 就是 REST 了，同时对于外界关于「什么算是 REST 什么不算是 REST」的争论没怎么关心过。

记得之前老赵提到过《REST in Practice》是本好书，所以我就收藏到 wish list 里面了，在 O’Reilly 打折时就下狠心买下来，然后看看争论得如此多的 REST 到底是什么东东。书中提到 Richardson 的 REST 成熟度模型，通过这个模型你可以理解什么是 REST 什么不是 REST。这个模型是这样子的：

第 0 级服务：只使用一个 URI 作为一个服务端口，也只使用一个 HTTP 方法传输数据。大多数 WS-* 服务都是这个级别的，XML-RPC 和 POX 也是。这种做法相当于把 HTTP 这个应用层协议降级为传输层协议用。HTTP 头和有效载荷是完全隔离的，HTTP 头只用于保证传输，不涉及业务逻辑；有效载荷包含全部业务逻辑，因此 API 可以无视 HTTP 头中的任何信息。

第 1 级服务：使用多个 URI，不同的 URI 代表不同的调用入口，但只使用同一个 HTTP 方法传输数据。

第 2 级服务：使用多个 URI，不同的 URI 代表不同的资源，同时使用多个 HTTP 方法操作这些资源，例如使用 POST/GET/PUT/DELET 分别进行 CRUD 操作。这时候 HTTP 头和有效载荷都包含业务逻辑，例如 HTTP 方法对应 CRUD 操作，HTTP 状态码对应操作结果的状态。我们现在看到的大多数所谓 RESTful API 做到的也就是这个级别。

第 3 级服务：使用超媒体（hypermedia）作为应用状态引擎。要解释这个概念先要解释什么是超媒体：

我们已经知道什么是多媒体（multimedia），以及什么是超文本（hypertext）。其中超文本特有的优势是拥有超链接（hyperlink）。如果我们把超链接引入到多媒体当中去，那就得到了超媒体，因此关键角色还是超链接。使用超媒体作为应用引擎状态，意思是应用引擎的状态变更由客户端访问不同的超媒体资源驱动。

举个例子来说，用户在论坛的帖子列表点击超链接进入某个帖子，这时候浏览器作为一个客户端就会去 GET 这个帖子的链接 URI，应用状态就切换为显示某个帖子了。接着用户输入回复提交表单，浏览器就会根据 form 上面的 action 属性 POST 内容给目标 URI，应用状态就再一次发生切换，完成了回复的存储。

使用超媒体与前面第 1 级、第 2 级的显著区别是，客户端不再和 URI 紧耦合。在第 1 级或者第 2 级的应用里面，客户端都需要知道资源使用的 URI 模版（如 /orders/{id}），然后要操作什么样的资源就生成什么样的 URI。超媒体客户端只知道入口 URI，之后的每一个 URI 都是通过超链接获得的。

还是用上述论坛例子来解释，假若这个论坛通过 Atom 协议支持非浏览器的客户端访问。客户端是不需要知道论坛帖子的 URI 模版的，因为客户端可以通过帖子列表的 Atom 获得帖子的超链接，然后在用户选择浏览帖子时获取对应 URI 的内容。获取回来的结果不会带有 form，但会带有 <link rel="reply" />，通过这个 link 客户端又知道了用户提交的回复应该发往哪个 URI。

说完 Richardson 的成熟度模型，说说 REST 这篇论文作者 Roy Fielding 的回应。Roy Fielding 说「只有使用了超媒体的才能算是 REST」。简单来说，他认为第 3 级成熟度以外的都不算 REST。我个人的看法是，我支持 Roy Fielding 对 REST 的严格定义，我也认为一个真正使用了超媒体实现应用状态引擎的服务非常了不起，但是在普通 CRUD API 能满足需求的情况下我觉得使用 CRUD API 也可以。

这本书后面还讲到了如何使用缓存来增加系统健壮性，如何使用 Atom 和 Atom 发布协议，如何使用 OpenID 和 OAuth 等认证授权技术。因为这本书我还没看完，所以这些内容我也不好做评价。

这本书总体来说写得不错，但就是废话稍微多了一点点。如果你跳着章节地去看，可能就不会觉得那是废话了，因为你挑选出来阅读的部分都包含所有的信息。但如果你像我这样从头到尾地阅读，就会觉得作者怎么前面提到过的事情后面还要再提及。

此外这本书提供的大量 .NET 和 Java 代码对我来说没什么意义。我觉得这本书更多是写给做企业服务的人看的，希望他们的思维模式能够从企业环境里常见的 WS-* 跳出来，同时希望证明给他们看实现 REST 是多么简单的事情。这对于天天研究互联网服务的我来说没什么必要，况且我也很久没写过 .NET 代码了，所以各式各样的示例代码给我无视掉了。我觉得我知道这件事情 WCF 能做也就足够了。