引子
API和SDK作為強(qiáng)大的技術(shù)抵蚊,目前在互聯(lián)網(wǎng)行業(yè)中被廣泛使用躏升。然而在生物信息行業(yè)中,對(duì)其了解节榜、掌握和使用的人卻很少羡玛。故作為GeneDock生物信息工程師的本文作者,希望通過這個(gè)博客全跨,記錄自己學(xué)習(xí)API和SDK的心得缝左,也幫助更多其他生物信息從業(yè)人員使用它亿遂。
背景介紹
什么是API浓若?
API(Application Programming Interface)是一組規(guī)則、協(xié)議或工具蛇数,清楚地定義了不同軟件部分之間通信的方法挪钓。其將應(yīng)用程序(application)的實(shí)現(xiàn)過程隱藏,只暴露調(diào)用所必須的部分耳舅,供其他開發(fā)者使用碌上。
舉個(gè)例子,大部分人都不知道投影儀的實(shí)現(xiàn)過程和原理浦徊,但是很多人都可以按照產(chǎn)品說明書馏予,將電腦通過數(shù)據(jù)線連接到投影儀上,最終放映幻燈片盔性。
相似地霞丧,你可能不知道一個(gè)應(yīng)用程序(例如google map)的實(shí)現(xiàn)過程和原理,但是通過閱讀API文檔冕香、調(diào)用API蛹尝,你就可以方便地使用這個(gè)應(yīng)用程序后豫。
再進(jìn)一步,GeneDock平臺(tái)也提供了API和SDK突那,您可以不知道GeneDock產(chǎn)品的實(shí)現(xiàn)過程挫酿、數(shù)據(jù)庫結(jié)構(gòu)、后臺(tái)代碼愕难,只需調(diào)用GeneDock的API早龟,就可以方便地、自動(dòng)地使用我們GeneDock系統(tǒng)了务漩。
什么是SDK拄衰?
SDK(Software Development Kit)往往是對(duì)一個(gè)或者多個(gè)API的封裝,形成軟件包饵骨,更進(jìn)一步地方便其他開發(fā)者使用翘悉。不同的編程語言會(huì)有不同版本的SDK(例如GeneDock目前提供python和java版本的SDK),但是調(diào)用的是同一套API居触。
什么是Web API妖混?
Web API是一種應(yīng)用在互聯(lián)網(wǎng)領(lǐng)域的API。目前很多互聯(lián)網(wǎng)應(yīng)用通常使用“客戶端-服務(wù)端模式”(client-server model):客戶端(例如chrome等瀏覽器)根據(jù)服務(wù)入口(endpoint)轮洋,發(fā)送請(qǐng)求(request)制市,后端接受請(qǐng)求后做出相應(yīng)的響應(yīng)(response)。
舉個(gè)例子弊予,打開瀏覽器祥楣,在地址欄中輸入“https://genedock.com”,點(diǎn)擊回車汉柒,會(huì)返回GeneDock的首頁误褪。這個(gè)過程可以分解為:
- 您的瀏覽器(客戶端client-side)通過URL(服務(wù)入口endpoint)向GeneDock后端(服務(wù)端server-side)發(fā)送了一個(gè)“獲取首頁”的請(qǐng)求(request);
- GeneDock后端服務(wù)做出響應(yīng)(response)返回一個(gè)html文件碾褂;
- 該文件經(jīng)過瀏覽器渲染兽间,即是您看到的GeneDock首頁了。
實(shí)際的過程可能是多次請(qǐng)求-響應(yīng)正塌,但是整體邏輯類似嘀略。
什么是RESTful API?
RESTfull API是一套web API的設(shè)計(jì)風(fēng)格或理論乓诽,它對(duì)API設(shè)計(jì)進(jìn)行了規(guī)定和限制帜羊。符合REST風(fēng)格的API會(huì)更方便、更簡(jiǎn)潔鸠天、更可靠讼育。
基于資源(Resource Based)
例如,RESTful API會(huì)規(guī)定,API的設(shè)計(jì)要基于資源而非動(dòng)作窥淆,基于名詞而非動(dòng)詞卖宠。
舉個(gè)例子,GeneDock的API基于工具忧饭、工作流扛伍、任務(wù)進(jìn)行設(shè)計(jì),而不會(huì)基于創(chuàng)建(create)词裤、更新(put)刺洒、刪除(delete)或者給出列表(list)來設(shè)計(jì)。
統(tǒng)一接口(Uniform Interface)
使用HTTP動(dòng)詞(HTTP verbs)來表示動(dòng)作吼砂,使用含有資源名稱的URI逆航,響應(yīng)(HTTP response)包含狀態(tài)碼(status)和內(nèi)容(body)。
常用的HTTP動(dòng)詞
動(dòng)詞 | 解釋 |
---|---|
GET | 類似于獲取 |
POST | 類似于創(chuàng)建 |
PUT | 類似于更新 |
DELETE | 類似于刪除 |
常用的狀態(tài)碼
狀態(tài)嗎 | 解釋 |
---|---|
2xx | 成功 |
4xx | 客戶端錯(cuò)誤 |
5xx | 服務(wù)端錯(cuò)誤 |
實(shí)際操作
使用python調(diào)用ListTool API
介紹完上邊的一些背景知識(shí)渔肩,我們具體演示一下因俐,通過python的requests包調(diào)用GeneDock的ListTool API來獲取某一賬號(hào)下的工具列表。
注意周偎,本文使用python抹剩,其他編程語言也有類似功能,但是限于作者能力蓉坎,目前只演示python版本澳眷。另,本文使用python 2.7版本蛉艾,python 3以上操作類似钳踊。
安裝requests包
通過python的包管理工具pip安裝requests包。
|
|
請(qǐng)求簽名
調(diào)用GeneDock API勿侯,首先要進(jìn)行請(qǐng)求簽名拓瞪,以保證數(shù)據(jù)的安全性。但是罐监,由于請(qǐng)求簽名算法比較復(fù)雜吴藻,而且具體步驟我也不太懂瞒爬,此處略去弓柱。
您可以直接復(fù)制下方代碼(定義了一個(gè)供requests包直接進(jìn)行請(qǐng)求簽名的GeneDockAuth
類),或使用我們的python SDK(后邊會(huì)介紹)侧但。
具體算法可以參考我們的API文檔-請(qǐng)求簽名矢空。
|
|
調(diào)用GeneDock ListTool API
定義變量api_endpoint、access_key_id和access_key_secret禀横。
|
|
由于ListTool API的請(qǐng)求語法是Get /accounts/<account_name>/projects/<project_name>/tools/ HTTP/1.1
屁药,為您的賬號(hào)名,為項(xiàng)目名柏锄,目前為default酿箭。
|
|
最終返回的resp變量是一個(gè)requests包響應(yīng)的類requests.models.Response
。您可以進(jìn)一步打印其中變量缭嫡。
|
|
如果返回的狀態(tài)碼是200缔御,至此,您就已經(jīng)成功使用python的requests包妇蛀,通過調(diào)用GeneDock ListTool API耕突,列出了您賬號(hào)下的工具。
注意調(diào)用API的響應(yīng)結(jié)果是json格式评架,若想形成列表眷茁,您可能還需要接著學(xué)習(xí)python的json包。
使用GeneDock的python SDK調(diào)用ListTool API
正如上文提到的纵诞,由于SDK是對(duì)一個(gè)或者多個(gè)API的封裝上祈,因此通過SDK調(diào)用API更加簡(jiǎn)單。
安裝GeneDock的python SDK
下載python SDK安裝包浙芙,解壓文件后雇逞,運(yùn)行代碼:
|
|
請(qǐng)求簽名
由于python SDK內(nèi)置了用于請(qǐng)求簽名的類GeneDockAuth
,故您可以直接使用茁裙。
|
|
調(diào)用GeneDock ListTool API
|
|
打印結(jié)果
|
|
相比與直接調(diào)用API,通過SDK來調(diào)用API晤锥,不僅更加方便掉蔬,而且還提供了很多變量,方便用戶使用矾瘾。
更多API和SDK的例子可以參考我們的api-reference和python?or?java?SDK手冊(cè)女轿。
結(jié)語
通過調(diào)用API和SDK的方法,對(duì)于使用者的編程能力是有一定的要求的壕翩。但是蛉迹,一旦掌握,您可以在程序中直接調(diào)用放妈,實(shí)現(xiàn)自動(dòng)化北救、批量化,極大地方便系統(tǒng)之間的交互芜抒,實(shí)現(xiàn)強(qiáng)大的功能珍策。
另外,我們目前正在開發(fā)基于SDK的命令行工具(command line tool)進(jìn)一步來調(diào)用API宅倒,屆時(shí)使用起來將會(huì)更加方便攘宙。敬請(qǐng)期待…
閱讀原文:https://www.genedock.com/blog/2017/03/08/api-sdk_for-bioinfo/#container