2017-03-08HuanWei Wang

生信同学API和SDK学习笔记

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

引子

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的<a href=”https://www.genedock.com/article/docs/seqflow/developer/api/tool/Tool 相关/#ListTool”-target=”_blank”>ListTool-API来获取某一账号下的工具列表。

注意，本文使用python，其他编程语言也有类似功能，但是限于作者能力，目前只演示python版本。另，本文使用python 2.7版本，python 3以上操作类似。

安装requests包

通过python的包管理工具pip安装requests包。

pip install requests

请求签名

调用GeneDock API，首先要进行请求签名，以保证数据的安全性。但是，由于请求签名算法比较复杂，而且具体步骤我也不太懂，此处略去。

您可以直接复制下方代码（定义了一个供requests包直接进行请求签名的GeneDockAuth类），或使用我们的python SDK（后边会介绍）。

具体算法可以参考我们的API文档-<a href=”https://www.genedock.com/article/docs/seqflow/developer/api/API-Reference/#请求签名"-target="_blank">请求签名。

#!/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

定义变量<a href=”https://www.genedock.com/article/docs/seqflow/developer/api/API-Reference/#服务入口"-target="_blank">api_endpoint、<a href=”https://www.genedock.com/article/docs/seqflow/developer/api/API-Reference/#访问密钥"-target="_blank">access_key_id和access_key_secret。

api_endpoint = "https://cn-beijing-api.genedock.com"  # 此处以北京域的API入口为例
access_key_id = "xxxxxxxxxxx"                         # 您的access_key_id
access_key_secret = "xxxxxxxxxxx"                     # 您的access_key_secret

由于<a href=”https://www.genedock.com/article/docs/seqflow/developer/api/tool/Tool 相关/#ListTool”-target=”_blank”>ListTool-API的请求语法是Get /accounts/<account_name>/projects/<project_name>/tools/ HTTP/1.1，<account_name>为您的账号名，<project_name>为项目名，目前为default。

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。您可以进一步打印其中变量。

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安装包，解压文件后，运行代码：

 python setup.py install

请求签名

由于python SDK内置了用于请求签名的类GeneDockAuth，故您可以直接使用。

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

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()

打印结果

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，届时使用起来将会更加方便。敬请期待…

<<上一篇

如何解决生物信息大规模计算的问题

下一篇>>

GeneDock HG，99元的全基因组分析服务面世