生信同学API和SDK学习笔记

2017-06-23  本文已影响0人  GeneDock

引子

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
上一篇下一篇

猜你喜欢

热点阅读