建站
咨詢(xún)
售后
建站咨詢(xún)
新聞中心
如今，隨著我們構(gòu)建軟件方式的變化，以及API平臺(tái)的爆炸式激增，各大公司都必須以更快的速度構(gòu)建出自己的產(chǎn)品、并推向市場(chǎng)。目前，幾乎所有的軟件需求都需要通過(guò)API來(lái)提供相應(yīng)的解決方案，其中包括：支付類(lèi)API、通信類(lèi)API、以及傳輸類(lèi)API等數(shù)千種。那么我們?cè)撊绾卧O(shè)計(jì)并構(gòu)建出一個(gè)優(yōu)質(zhì)的API呢?
無(wú)論您的目標(biāo)是要構(gòu)建一個(gè)開(kāi)源的API、一種API平臺(tái)(https://dzone.com/articles/what-is-an-api-platform)、還是能幫助其他開(kāi)發(fā)者與自己的產(chǎn)品相集成的API，您都必須努力優(yōu)化開(kāi)發(fā)者的API體驗(yàn)(DX)。
無(wú)論作為產(chǎn)品經(jīng)理，還是技術(shù)開(kāi)發(fā)人員，您都需要在每個(gè)API的設(shè)計(jì)決策上，充分考慮到最終用戶(hù)，只有這樣他們才會(huì)愿意使用您開(kāi)發(fā)出的API。在此方面，F(xiàn)acebook就是一個(gè)非常好的例子。在早期，他們?cè)谏缃幻襟w的游戲平臺(tái)上就開(kāi)辟了一個(gè)強(qiáng)大的開(kāi)發(fā)者社區(qū)，以方便大家構(gòu)建出不同的游戲。當(dāng)然Facebook也能夠從中獲利。
為了能夠在不斷變化與發(fā)展的SaaS環(huán)境中脫穎而出，您可以通過(guò)授權(quán)用戶(hù)構(gòu)建自定義的應(yīng)用程序(甚至是在您所不了解的平臺(tái)上提供完美的使用體驗(yàn))，來(lái)讓他們產(chǎn)生所謂“駕馭的快感”。
一般而言，普通API應(yīng)當(dāng)具有如下基本特性：
- 具有一定的魯棒性，以保證99.9%(或更高)的正常運(yùn)行時(shí)間
- 具有快速響應(yīng)能力，或響應(yīng)耗時(shí)較短
- 能夠無(wú)縫更新，或無(wú)需引入重大變更操作
- 能夠公布各個(gè)構(gòu)建的模塊，而非一個(gè)靜態(tài)固化的解決方案
下面，我們將和您深入討論設(shè)計(jì)優(yōu)質(zhì)API所應(yīng)當(dāng)注意的五個(gè)方面：
- 縮短寶貴的時(shí)間
- 將您的文檔置于網(wǎng)站的主頁(yè)
- 在API中保證抽象的一致性
- 設(shè)計(jì)面向未來(lái)的API
- 妥善管理好潛在的變更
1.縮短寶貴的時(shí)間
一個(gè)優(yōu)質(zhì)的API應(yīng)當(dāng)能夠縮短開(kāi)發(fā)人員的寶貴時(shí)間(TtV)。也就是說(shuō)，在開(kāi)發(fā)人員開(kāi)始與您的API集成之前，就能夠根據(jù)對(duì)應(yīng)的用戶(hù)手冊(cè)，測(cè)試有關(guān)cURL(譯者注：一種利用URL語(yǔ)法，工作在命令行里的文件傳輸工具)的響應(yīng)，以證明API自身的使用價(jià)值。您可以在Nylas文檔(https://docs.nylas.com/reference)中，找到類(lèi)似的示例。
即使您能夠提供測(cè)試令牌(test tokens)，使用一通百通(first-time-every-time)的框架也非常重要的。通過(guò)使用測(cè)試令牌的相關(guān)范例，那些不熟悉cURL命令操作的開(kāi)發(fā)人員，也能夠像其他人那樣來(lái)測(cè)試令牌的進(jìn)程，檢查API是否能夠完全按照設(shè)定運(yùn)行下去。此處正好需要配有良好的文檔說(shuō)明。
符合用戶(hù)的期望
在構(gòu)建API時(shí) ，請(qǐng)牢記一個(gè)問(wèn)題：該API是否完全符合，用戶(hù)期望在第一次嘗試時(shí)所執(zhí)行的操作?
在大多數(shù)情況下，您需要在API的實(shí)用性方面采取“首次把將正確的事做對(duì)(do the right thing right the first time)”的方法，以保障所提供的API的確能夠縮短開(kāi)發(fā)者寶貴的時(shí)間(TtV)。從開(kāi)發(fā)人員第一次交互開(kāi)始，該API就能夠快速有效地解決那些具有挑戰(zhàn)性的技術(shù)問(wèn)題。因此，請(qǐng)定期檢查并測(cè)試自己的API，確保用戶(hù)能夠順利地完成首次互動(dòng)，并為后續(xù)使用樹(shù)立信心。
使用SDK來(lái)提高效率
SDK是減少集成過(guò)程出現(xiàn)“摩擦”的合適方法之一。它對(duì)于確保開(kāi)發(fā)人員能夠盡快地找出API中的SDK集成參數(shù)，也是非常重要的。通過(guò)使用簡(jiǎn)單的Ruby、NodeJS或Python SDK，開(kāi)發(fā)人員可以在較短的時(shí)間內(nèi)，了解API是如何在其選擇的框架內(nèi)運(yùn)行的，進(jìn)而高效地完成功能齊備的集成。記?。弘m然SDK需要花費(fèi)一定的時(shí)間來(lái)創(chuàng)建和維護(hù)，但它們的確能夠顯著地改善開(kāi)發(fā)人員的體驗(yàn)、并降低他們的TtV。
2.將您的文檔視為網(wǎng)站的主頁(yè)
由于在您的首頁(yè)上就能獲取API的相關(guān)文檔，因此開(kāi)發(fā)人員可以將其加入瀏覽器的書(shū)簽、或放置到顯著的位置。當(dāng)然，您的API文檔不但要直觀且用戶(hù)友好，而且要能夠遵循一定的邏輯流程。
說(shuō)到API文檔的易獲取性和易用性，Stripe(https://stripe.com/)就是一個(gè)很好的例子。如下圖所示，它的文檔易于導(dǎo)航，左側(cè)邊欄上有著清晰的目錄，右側(cè)則是Stripe API成功付款的簡(jiǎn)單6步流程：
如果您的API中有許多需要全面進(jìn)行文檔解釋的復(fù)雜元素，那么您的文檔庫(kù)應(yīng)該通過(guò)內(nèi)置的搜索功能，方便開(kāi)發(fā)人員進(jìn)行遍歷查詢(xún)。同時(shí)文檔也應(yīng)當(dāng)以一致性的方式進(jìn)行邏輯性組織，并在整個(gè)API集成的過(guò)程中做好針對(duì)上下文的內(nèi)容覆蓋。
此處的“上下文”是指，讓每一位開(kāi)發(fā)人員都能選擇不同的編程語(yǔ)言?？梢?jiàn)，列出針對(duì)某一種語(yǔ)言的API使用技術(shù)指南是不夠的，您的文檔需要具有不同語(yǔ)言的適用性，甚至是滿(mǎn)足某些特定開(kāi)發(fā)技術(shù)(各種SDK、或自定義代碼語(yǔ)言)的解決方案。畢竟，某位開(kāi)發(fā)人員很可能正在使用您的API技術(shù)，去解決某個(gè)獨(dú)特的問(wèn)題，因此他們需要查看與之相關(guān)的各種指南、示例、以及快速入門(mén)。同時(shí)，這也是展示與證明您的API具備全面性和可擴(kuò)展性的良機(jī)。
3.在API中保證抽象的一致性
為了方便開(kāi)發(fā)人員的使用，并提高API的實(shí)用性，您需要在API中保證抽象工作流的一致性。
您可以使用相同的POST請(qǐng)求，在不同的Google和Exchange事件中獲得完整的CRUD(增加Create、讀取Read、更新Update和刪除Delete)。盡管Google和Exchange不同事件的數(shù)據(jù)模型差別較大，但是開(kāi)發(fā)人員沒(méi)有必要以不同的方式，來(lái)開(kāi)展代碼的編程工作。
當(dāng)然，您不必過(guò)于苛求抽象的一致性，而刻意忽略了個(gè)別特例。例如，您可能為了顧及產(chǎn)品的通用一致性，而未能及時(shí)地拋出在某種環(huán)境下API的異常信息，導(dǎo)致開(kāi)發(fā)人員無(wú)法跟蹤到程序的某項(xiàng)缺陷。因此，請(qǐng)務(wù)必找到一個(gè)合理的平衡點(diǎn)。
4.設(shè)計(jì)面向未來(lái)的API
如今，業(yè)界傾向于通過(guò)JSON來(lái)導(dǎo)入和移出數(shù)據(jù)。但是在不久的將來(lái)，大家也許會(huì)大量使用到GraphQL API(譯者注：既是一種可用于API查詢(xún)的語(yǔ)言，又是一種滿(mǎn)足數(shù)據(jù)查詢(xún)的運(yùn)行時(shí))。開(kāi)發(fā)人員通過(guò)檢查您的API，以消除其工作流程中的各種“摩擦”。因此，如果您的API無(wú)法遵循開(kāi)發(fā)領(lǐng)域的最新無(wú)摩擦(frictionless)趨勢(shì)的話，那么您的API很可能會(huì)失去競(jìng)爭(zhēng)力。例如，雖然大多數(shù)開(kāi)發(fā)人員期望用JSON來(lái)響應(yīng)cURL的命令。但是您可以做得更加豐富一些。通過(guò)發(fā)送各種簡(jiǎn)單的JSON響應(yīng)，來(lái)代替二進(jìn)制的XML和SOAP，這樣不但能夠最小化摩擦，還能夠?yàn)殚_(kāi)發(fā)人員創(chuàng)造更好的體驗(yàn)。
5.妥善管理好潛在的變更
在構(gòu)建API時(shí)，更改往往是不可避免的。由SOAP API引出了REST API，而REST API則是GRAPH API的前身。JSON雖然是如今API的行業(yè)標(biāo)準(zhǔn)化文件格式，但隨著技術(shù)的發(fā)展，面對(duì)任何可能出現(xiàn)的變化，你需要從如下方面來(lái)妥善管理自己的API：
從第1天開(kāi)始就內(nèi)置版本控制
創(chuàng)新的數(shù)字支付提供商Stripe就采用了相當(dāng)嚴(yán)格的管控方法。為了避免由于倉(cāng)促或不正確的API變更，對(duì)于業(yè)務(wù)產(chǎn)生的嚴(yán)重影響，他們從最初的概念到最終的推出，都實(shí)施了嚴(yán)格的Stripe API版本控制，并保證向后兼容性。在具體實(shí)踐中，您對(duì)于API的版本控制可能不如成熟企業(yè)那樣復(fù)雜和專(zhuān)業(yè)，但是您完全可以使用簡(jiǎn)單的版本編號(hào)系統(tǒng)(如：V1、V1.1、V1.2等)，來(lái)更好地、有效地實(shí)現(xiàn)版本擴(kuò)展與管控。
盡早和經(jīng)常性地溝通變更
另一方面，作為業(yè)界的大廠，F(xiàn)acebook頻繁地對(duì)其API進(jìn)行著變更和調(diào)整，這讓全世界的網(wǎng)絡(luò)和移動(dòng)應(yīng)用開(kāi)發(fā)人員經(jīng)常愛(ài)恨交織。不過(guò)，F(xiàn)acebook每次都會(huì)提前通知此類(lèi)變更。因此只要您的開(kāi)發(fā)人員能夠提前做好準(zhǔn)備，就不至于被動(dòng)地影響到最終用戶(hù)的服務(wù)?？梢?jiàn)，如果您沒(méi)有實(shí)力來(lái)構(gòu)建版本控制系統(tǒng)的話，應(yīng)盡早且經(jīng)常性地與各個(gè)方面溝通變更信息，這是一種更低成本、更靈活主動(dòng)的處理方式。
總結(jié)
綜上所述，您需要確保自己的API在第一次被試用時(shí)就能如期運(yùn)行，并籍此建立與各類(lèi)開(kāi)發(fā)人員的信任基礎(chǔ)與使用愿望。這雖然聽(tīng)起來(lái)極其簡(jiǎn)單，但是在實(shí)踐中也充滿(mǎn)了挑戰(zhàn)。希望上述五種實(shí)踐“秘籍”，能夠幫助您構(gòu)建屬于自己的優(yōu)質(zhì)API，并能給開(kāi)發(fā)者帶來(lái)不俗的體驗(yàn)。
原文標(biāo)題：Secrets to Great API Design，作者：Tasia Potasinski
【譯稿，合作站點(diǎn)轉(zhuǎn)載請(qǐng)注明原文譯者和出處為.com】
名稱(chēng)欄目：解鎖設(shè)計(jì)優(yōu)質(zhì)API的五種秘籍
文章出自：http://m.fisionsoft.com.cn/article/cccioid.html
