如何开发 API 客户端程序

1. 概述

在开发过程中，总会遇到要对接一些产品的 api 接口，比如，你做商城系统，必须得对接支持接口，如果做公众号开发，也必须对接微信接口，还有，假如你的网站要集成 QQ，微博账号登录，那也得对接相应的接口。所以开发 api 客户端程序是每个程序员必须掌握的技能。通常，想要开发一些 api 接口，那就必须得精读相应产品的 api 接口文档，只有仔细研究了这些文档，理解每个接口的含义，才能更好地开发出功能强大的 api 接口客户端程序。

然而，这么多文档接口都是遵循一定的规则来开发的，比如，使用 http 协议，只要掌握这些基本的规则或者理解透 http 协议，无论开发哪个接口客户端，都会简单。

2. 流程

开发一个产品的 api 客户端产品，第一步是要熟读 api 接口文档。如果接口文档看不懂，那就没法进行开发的。第二步就是选择一个自己熟悉的编程语言的库来快速开发。比如这篇文章ruby 的 http request 库介绍就介绍了很多用 ruby 编写的实现 http 请求的库。

一般来说，我们开发的是 http api 接口，如果对 http 协议比较熟悉，那还是比较容易开发的。http 协议不外乎就是客户端发送请求，然后服务器响应请求，而客户端又把响应的请求解析出来，进行后续的处理。http 发送请求这个过程中，那就是 http 协议的请求过程，可能需要发送以下的信息:

• http 协议的版本，通常是 1.1
• 请求的资源，比如 url 地址
• 请求的头部信息，比如 content-type 等
• 请求的方法，比如 GET，POST
• 请求的参数或内容，比如表单的内容，json 数据，xml 数据等。

但是，除此之外，服务器端不能让客户端随意就能连接吧，总是需要为了安全，有个认证的过程，需要来验证客户端的合法性。这种过程可以用 http 基本认证，就是那种最基础的用户名和密码的形式。不过这种是不太安全，因为很容易被枚举。一般用得比较多的是对称加密，就是提供 access_key 和 secret_key，access_key 是公钥，而 secret_key 是私钥，它们是成对出现的，按照对称性加密的原理，用公钥加密的信息，只能用配对的私钥解密，公钥可以暴露，私钥不可以，一般来说，最好都不泄露出去。

要对接一些产品的 api 接口，有可能首先第一步就是要生成这一对密钥，需要保存到你的代码中。根据这对密钥就可以生成一个叫"access_token"的串，这个串是存在服务器中，有一定的时效，每次能过对称加密认证过后的访问就要自动带上这个 access_token，这样就不用每次都生成。而除了对称加密的认证方法，还有 oauth2 之类，每章不对此进行详述。

3. 测试工具

测试主要是在了解和读懂 api 文档的基础上进行的，读懂了 api 文档的接口功能说明，我们要对这个功能进行测试，看它是不是跟我们预期所想的结果。测试完之后，我们再把它的功能转化为编程语言来实现。

第一个测试工具是 curl。它是 linux 下的，使用它可以很简单的模拟 http 请求，只要会使用命令行即可，还有，有很多 api 文档都有它的示例。如果对 curl 很熟悉，要转化成对应的编程语言来实现，也是比较简单的。

第二个测试工具是 postman，它是 chrome 浏览器的一个插件。它有图形化的客户端功能，可以更改请求的头部信息，发送 json，xml 数据，还能对响应的数据排版，预览。

4. 案例

对于那种不需要验证的 api 客户端程序部分，要开发是比较简单，只要找准正确的 url 地址，用相应的请求方法 (GET，POST 等)，传递适当的请求参数或数据就可以了。所以重点开发和关注的部分应该是认证那一块，不同的 api 服务有不同的规则，在生成 access_token 的时候，除了需要上文所说的 access_key 和 access_secret 之外，还可能需要各种随机串，时间串，根据不同结合，再用 md5 或 sha1 等来加密，最后才生成 access_token。

下面简单介绍几个 api 客户端的开发案例并介绍它们的客户端库。

4.1 阿里云 oss

阿里云 oss 是一个云存储服务器，可以存储文件，图片等非结构化数据。它有两种对象类型，一种叫Bucket，它相当于一个命令空间，是具有全局唯一，所有的图片文件都存在它上面，还有另一种，叫 Object，也就是文件，图片等信息的对象实体。假如要上传一个文件或图片，就是创建一个 Object。它的 api 文档在这里: http://doc.oss.aliyuncs.com/。

阿里云 oss 提供一对密钥，分别是Access Key ID、Access Key Secret。我们要根据这对密钥生成认证签名。阿里云 oss 的 api 有两种认证签名，分别是在Head中包含签名和在URL中包含签名。

在Head中包含签名很简单，就是在请求头部中增加一项，叫Authorization，它的值是按照一定规则计算的串。

Authorization字段计算方法如下：
"Authorization: OSS " + Access Key ID + ":" + Signature

Signature = base64(hmac-sha1(VERB + "\n"
                    + CONTENT-MD5 + "\n"
                    + CONTENT-TYPE + "\n"
                    + DATE + "\n"
                    + CanonicalizedOSSHeaders
                    + CanonicalizedResource))

具体的方法说明，可以看文档中的 4.2 那一节"在 Head 中包含签名"。

carrierwave-aliyun这个库有对这部分代码的具体实现。

# https://github.com/huacnlee/carrierwave-aliyun/blob/master/lib/carrierwave/storage/aliyun.rb#L142
def sign(verb, path, content_md5 = '', content_type = '', date)
  canonicalized_oss_headers = ''
  canonicalized_resource = "/#{URI.decode(path)}"
  string_to_sign = "#{verb}\n\n#{content_type}\n#{date}\n#{canonicalized_oss_headers}#{canonicalized_resource}"
  digest = OpenSSL::Digest.new('sha1')
  h = OpenSSL::HMAC.digest(digest, @aliyun_access_key, string_to_sign)
  h = Base64.encode64(h)
  "OSS #{@aliyun_access_id}:#{h}"
end

在URL中包含签名是为了让表单在上传的时候，不通过 web 服务器作中转，而直接上传到 oss 服务器中。所以它需要在上传的地方，也就是用 form 表单，form 的地址要写阿里云 oss 的服务器 api 地址，而这个地址就是要通过认证签名生成的。类似下面的地址：

http://oss-example.oss.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=44CF9590006BF252F707&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D

具体的计算规则可以 api 文档的 4.3 那一节"在 URL 中包含签名"。

关于阿里云 oss 的 api 官方有一个 ruby 的实现：http://help.aliyun.com/document_detail/oss/sdk/ruby-sdk/install.html。

完结。