生信同学API和SDK学习笔记

引子

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的首页。这个过程可以分解为：

  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

介绍完上边的一些背景知识，我们具体演示一下，通过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
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 203,456评论 5赞 477
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,370评论 2赞 381
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 150,337评论 0赞 337
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,583评论 1赞 273
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,596评论 5赞 365
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,572评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,936评论 3赞 395
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,595评论 0赞 258
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,850评论 1赞 297
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,601评论 2赞 321
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,685评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,371评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,951评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,934评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,167评论 1赞 259
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 43,636评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,411评论 2赞 342

推荐阅读更多精彩内容

  • Spring Cloud
    Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具（例如配置管理，服务发现，断路器，智...
    卡卡罗2017阅读 134,585评论 18赞 139
  • Android - 收藏集
    Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 171,398评论 25赞 707
  • Python--Flask Django等常用库总结
    # Python 资源大全中文版 我想很多程序员应该记得 GitHub 上有一个 Awesome - XXX 系列...
    aimaile阅读 26,436评论 6赞 428
  • Python 资源大全中文版
    GitHub 上有一个 Awesome - XXX 系列的资源整理,资源非常丰富，涉及面非常广。awesome-p...
    若与阅读 18,612评论 4赞 418
  • 山阳之歌（歌词）
    漫游古道，芳草碧连天告别繁华， 领略山外山好一处幽静雅致的好风景哟过了秦岭向南看就到了山阳县 北通到商洛走南是漫川...
    诗缘文字书法部落阅读 510评论 5赞 2