引子
API和SDK作为强大的技术，目前在互联网行业中被广泛使用。然而在生物信息行业中，对其了解、掌握和使用的人却很少。故作为GeneDock生物信息工程师的本文作者，希望通过这个博客，记录自己学习API和SDK的心得，也帮助更多其他生物信息从业人员使用它。
背景介绍
什么是API？
API（Application Programming Interface）是一组规则、协议或工具，清楚地定义了不同软件部分之间通信的方法。其将应用程序（application）的实现过程隐藏，只暴露调用所必须的部分，供其他开发者使用。
举个例子，大部分人都不知道投影仪的实现过程和原理，但是很多人都可以按照产品说明书，将电脑通过数据线连接到投影仪上，最终放映幻灯片。
相似地，你可能不知道一个应用程序（例如google map）的实现过程和原理，但是通过阅读API文档、调用API，你就可以方便地使用这个应用程序。
再进一步，GeneDock平台也提供了API和SDK，您可以不知道GeneDock产品的实现过程、数据库结构、后台代码，只需调用GeneDock的API，就可以方便地、自动地使用我们GeneDock系统了。
什么是SDK？
SDK（Software Development Kit）往往是对一个或者多个API的封装，形成软件包，更进一步地方便其他开发者使用。不同的编程语言会有不同版本的SDK（例如GeneDock目前提供python和java版本的SDK），但是调用的是同一套API。
什么是Web API？
Web API是一种应用在互联网领域的API。目前很多互联网应用通常使用“客户端-服务端模式”（client-server model）：客户端（例如chrome等浏览器）根据服务入口（endpoint），发送请求（request），后端接受请求后做出相应的响应（response）。
举个例子，打开浏览器，在地址栏中输入“https://genedock.com”，点击回车，会返回GeneDock的首页。这个过程可以分解为：
- 您的浏览器（客户端client-side）通过URL（服务入口endpoint）向GeneDock后端（服务端server-side）发送了一个“获取首页”的请求（request）；
- GeneDock后端服务做出响应（response）返回一个html文件；
- 该文件经过浏览器渲染，即是您看到的GeneDock首页了。
实际的过程可能是多次请求-响应，但是整体逻辑类似。
什么是RESTful API？
RESTfull API是一套web API的设计风格或理论，它对API设计进行了规定和限制。符合REST风格的API会更方便、更简洁、更可靠。
基于资源（Resource Based）
例如，RESTful API会规定，API的设计要基于资源而非动作，基于名词而非动词。
举个例子，GeneDock的API基于工具、工作流、任务进行设计，而不会基于创建（create）、更新（put）、删除（delete）或者给出列表（list）来设计。
统一接口（Uniform Interface）
使用HTTP动词（HTTP verbs）来表示动作，使用含有资源名称的URI，响应（HTTP response）包含状态码（status）和内容（body）。
常用的HTTP动词
| 动词 | 解释 |
|---|---|
| GET | 类似于获取 |
| POST | 类似于创建 |
| PUT | 类似于更新 |
| DELETE | 类似于删除 |
常用的状态码
| 状态吗 | 解释 |
|---|---|
| 2xx | 成功 |
| 4xx | 客户端错误 |
| 5xx | 服务端错误 |
实际操作
使用python调用ListTool API
介绍完上边的一些背景知识，我们具体演示一下，通过python的requests包调用GeneDock的ListTool API来获取某一账号下的工具列表。
注意，本文使用python，其他编程语言也有类似功能，但是限于作者能力，目前只演示python版本。另，本文使用python 2.7版本，python 3以上操作类似。
安装requests包
通过python的包管理工具pip安装requests包。
1 |
pip install requests |
请求签名
调用GeneDock API，首先要进行请求签名，以保证数据的安全性。但是，由于请求签名算法比较复杂，而且具体步骤我也不太懂，此处略去。
您可以直接复制下方代码（定义了一个供requests包直接进行请求签名的GeneDockAuth类），或使用我们的python SDK（后边会介绍）。
具体算法可以参考我们的API文档-请求签名。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 |
#!/usr/bin/env python # coding=utf8 import time import hashlib import hmac import base64 import requests HEADER_PREFIX = "x-gd-" AUTH_PREFIX = "GeneDock" # 从URL中获取资源表示 def extract_resource_from_url(url): if url.lower().startswith("http://"): idx = url.find('/', 7, -1) return url[idx:].strip() elif url.lower().startswith("https://"): idx = url.find('/', 8, -1) return url[idx:].strip() else: return url.strip() # 标准化资源表示 def canonicalize_resource(resource): res_list = resource.split("?") if len(res_list) <= 1 or len(res_list) > 2: return resource res = res_list[0] param = res_list[1] params = param.split("&") params = sorted(params) param = '&'.join(params) return res + '?' + param def convert_utf8(input_string): if isinstance(input_string, unicode): input_string = input_string.encode('utf-8') return input_string # 格式化HTTP头 def format_header(headers=None): if not headers: headers = {} tmp_headers = {} for k in headers.keys(): tmp_str = headers[k] if isinstance(tmp_str, unicode): tmp_str = convert_utf8(tmp_str) if k.lower().startswith(HEADER_PREFIX): k_lower = k.lower().strip() tmp_headers[k_lower] = tmp_str else: tmp_headers[k.strip()] = tmp_str return tmp_headers # GeneDockAuth类 class GeneDockAuth(requests.auth.AuthBase): def __init__(self, access_key_id, access_key_secret, verbose=True): self.access_key_id = access_key_id self.access_key_secret = access_key_secret self.verbose = verbose def __call__(self, r): method = r.method content_type = r.headers.get('Content-Type', '') content_md5 = r.headers.get('Content-MD5', '') canonicalized_gd_headers = "" date = time.strftime("%a, %d %b %Y %H:%M:%S GMT", time.gmtime()) resource = extract_resource_from_url(r.url) tmp_headers = format_header(r.headers) if len(tmp_headers) > 0: x_header_list = tmp_headers.keys() x_header_list.sort() for k in x_header_list: if k.startswith(HEADER_PREFIX): canonicalized_gd_headers += "%s:%s\n" % (k, tmp_headers[k]) canonicalized_resource = canonicalize_resource(resource) string_to_sign = method + "\n" + content_md5 + "\n" + content_type + "\n" + date + "\n" + canonicalized_gd_headers + canonicalized_resource h = hmac.new(self.access_key_secret.encode('utf-8'), string_to_sign, hashlib.sha1) signature = base64.encodestring(h.digest()).strip() r.headers["Date"] = date r.headers["Authorization"] = AUTH_PREFIX + " " + self.access_key_id + ":" + signature return r |
调用GeneDock ListTool API
定义变量api_endpoint、access_key_id和access_key_secret。
1 2 3 |
api_endpoint = "https://cn-beijing-api.genedock.com" # 此处以北京域的API入口为例 access_key_id = "xxxxxxxxxxx" # 您的access_key_id access_key_secret = "xxxxxxxxxxx" # 您的access_key_secret |
由于ListTool API的请求语法是Get /accounts/<account_name>/projects/<project_name>/tools/ HTTP/1.1，为您的账号名，为项目名，目前为default。
1 2 3 4 5 6 |
account_name = "XXXX" # 此处为您的账号名 project_name = "default" # 此处为项目名，目前为default api_resource = "/accounts/" + account_name + "/projects/" + project_name + "/tools/" resp = requests.get(api_endpoint + api_resource, auth=GeneDockAuth(access_key_id, access_key_secret)) |
最终返回的resp变量是一个requests包响应的类requests.models.Response。您可以进一步打印其中变量。
1 2 3 |
print resp.status_code # 返回的状态码 print resp.text # 返回的内容 print resp.json() # 以json格式展示返回内容 |
如果返回的状态码是200，至此，您就已经成功使用python的requests包，通过调用GeneDock ListTool API，列出了您账号下的工具。
注意调用API的响应结果是json格式，若想形成列表，您可能还需要接着学习python的json包。
使用GeneDock的python SDK调用ListTool API
正如上文提到的，由于SDK是对一个或者多个API的封装，因此通过SDK调用API更加简单。
安装GeneDock的python SDK
下载python SDK安装包，解压文件后，运行代码：
1 |
python setup.py install |
请求签名
由于python SDK内置了用于请求签名的类GeneDockAuth，故您可以直接使用。
1 2 3 4 |
import gdpy access_key_id = "xxxxxxxxxxx" # 您的access_key_id access_key_secret = "xxxxxxxxxxx" # 您的access_key_secret auth = gdpy.GeneDockAuth(access_key_id, access_key_secret) |
调用GeneDock ListTool API
1 2 3 4 5 |
api_endpoint = "https://cn-beijing-api.genedock.com" # 此处以北京域的API入口为例 account_name = "XXXX" # 此处为您的账号名 project_name = "default" # 此处为项目名，目前为default tool = gdpy.Tools(auth, api_endpoint, account_name, project_name) list_tool_result = tool.list_tools() |
打印结果
1 2 |
print list_tool_result.tools # 查看tool列表详情 print list_tool_result.count # 列出的tool的数量 |
相比与直接调用API，通过SDK来调用API，不仅更加方便，而且还提供了很多变量，方便用户使用。
更多API和SDK的例子可以参考我们的api-reference和python or java SDK手册。
结语
通过调用API和SDK的方法，对于使用者的编程能力是有一定的要求的。但是，一旦掌握，您可以在程序中直接调用，实现自动化、批量化，极大地方便系统之间的交互，实现强大的功能。
另外，我们目前正在开发基于SDK的命令行工具（command line tool）进一步来调用API，届时使用起来将会更加方便。敬请期待…
阅读原文：https://www.genedock.com/blog/2017/03/08/api-sdk_for-bioinfo/#container
网友评论