善学者,假人之长以补其短

(本文由GeneDock公司 Bioinformatics Engineer Huanwei Wang撰写,转载请保留作者信息和原文链接)

引子

API和SDK作为强大的技术,目前在互联网行业中被广泛使用。然而在生物信息行业中,对其了解、掌握和使用的人却很少。故作为GeneDock生物信息工程师的本文作者,希望通过这个博客,记录自己学习API和SDK的心得,也帮助更多其他生物信息从业人员使用它。

背景介绍

什么是API?

API(Application Programming Interface)是一组规则、协议或工具,清楚地定义了不同软件部分之间通信的方法。其将应用程序(application)的实现过程隐藏,只暴露调用所必须的部分,供其他开发者使用。

举个例子,大部分人都不知道投影仪的实现过程和原理,但是很多人都可以按照产品说明书,将电脑通过数据线连接到投影仪上,最终放映幻灯片。

相似地,你可能不知道一个应用程序(例如google map)的实现过程和原理,但是通过阅读API文档、调用API,你就可以方便地使用这个应用程序。

再进一步,GeneDock平台也提供了APISDK,您可以不知道GeneDock产品的实现过程、数据库结构、后台代码,只需调用GeneDock的API,就可以方便地、自动地使用我们GeneDock系统了。

什么是SDK?

SDK(Software Development Kit)往往是对一个或者多个API的封装,形成软件包,更进一步地方便其他开发者使用。不同的编程语言会有不同版本的SDK(例如GeneDock目前提供pythonjava版本的SDK),但是调用的是同一套API。

什么是Web API?

Web API是一种应用在互联网领域的API。目前很多互联网应用通常使用“客户端-服务端模式”(client-server model):客户端(例如chrome等浏览器)根据服务入口(endpoint),发送请求(request),后端接受请求后做出相应的响应(response)。

举个例子,打开浏览器,在地址栏中输入“https://genedock.com”,点击回车,会返回GeneDock的首页。这个过程可以分解为:

  1. 您的浏览器(客户端client-side)通过URL(服务入口endpoint)向GeneDock后端(服务端server-side)发送了一个“获取首页”的请求(request);
  2. GeneDock后端服务做出响应(response)返回一个html文件;
  3. 该文件经过浏览器渲染,即是您看到的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

介绍完上边的一些背景知识,我们具体演示一下,通过pythonrequests包调用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_endpointaccess_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-referencepython or java SDK手册。

结语

通过调用API和SDK的方法,对于使用者的编程能力是有一定的要求的。但是,一旦掌握,您可以在程序中直接调用,实现自动化、批量化,极大地方便系统之间的交互,实现强大的功能。

另外,我们目前正在开发基于SDK的命令行工具(command line tool)进一步来调用API,届时使用起来将会更加方便。敬请期待…