開發(fā)人員在考慮最終用戶的情況下創(chuàng)建軟件

這是軟件開發(fā)的本質(zhì)。開發(fā)人員在考慮最終用戶的情況下創(chuàng)建軟件。看起來很簡(jiǎn)單，但有時(shí)這些用戶也是開發(fā)人員。他們不需要為他們分解的東西。他們甚至不需要簡(jiǎn)單。他們想要的就是訪問 - 一種將軟件與他們的軟件集成的方法。這是API(應(yīng)用程序編程接口)的用武之地。在本文中，我希望強(qiáng)調(diào)您可以采取的五個(gè)步驟來創(chuàng)建成功的API。

談到軟件開發(fā)，我們都不想重新發(fā)明輪子。此時(shí)，幾乎所有大型Web公司都有其軟件產(chǎn)品的API。研究這些API并嘗試了解創(chuàng)建它們的不同設(shè)計(jì)決策。

有許多不同的技術(shù)，但您將看到的大多數(shù)API將使用RESTful接口或SOAP。如果你想要使用哪個(gè)API接口，我建議使用HTTP協(xié)議進(jìn)行RESTful方法。它比SOAP更簡(jiǎn)單，它目前更受歡迎，并且在使用基于Web的軟件產(chǎn)品時(shí)更容易上手。

始終如一

開發(fā)人員最欣賞的一點(diǎn)是一致性。除其他外，這包括可尋址性，輸入?yún)?shù)，輸出格式和錯(cuò)誤處理。

使用RESTful方法時(shí)，有許多不同的URI命名方案。每個(gè)人都有它的支持者，所以只需選擇一個(gè)并堅(jiān)持下去。輸入和輸出結(jié)構(gòu)也是如此。大多數(shù)API支持使用XML和JSON作為輸入和輸出格式。我建議支持兩者，但選擇默認(rèn)格式。

對(duì)于輸入，您的輸入要求應(yīng)該一致地命名，并且應(yīng)該在您正在進(jìn)行的API調(diào)用的上下文中有意義。對(duì)于輸出，請(qǐng)確保使用通用數(shù)據(jù)結(jié)構(gòu)布局。如果要將一個(gè)API調(diào)用的輸出包裝在 XML標(biāo)記中，請(qǐng)考慮使用其他調(diào)用執(zhí)行此操作。

通常的做法是在發(fā)送回客戶端的輸出數(shù)據(jù)中包含某種狀態(tài)標(biāo)志。使用RESTful API方法時(shí)，應(yīng)使用HTTP狀態(tài)代碼完成此操作。例如，如果您剛剛在現(xiàn)有數(shù)據(jù)對(duì)象上處理了PUT請(qǐng)求，則響應(yīng)中包含的HTTP狀態(tài)代碼將根據(jù)請(qǐng)求的結(jié)果而有所不同。

可以使用標(biāo)準(zhǔn)的“200 OK”狀態(tài)代碼來表示請(qǐng)求是成功的，而不是指示呼叫狀態(tài)的任意標(biāo)志，而可以使用“400 Bad Request”狀態(tài)代碼來表示請(qǐng)求是畸形。有很多HTTP狀態(tài)代碼可以在不同的情況下使用。

使用OAuth

大多數(shù)軟件產(chǎn)品都涉及某種用戶身份驗(yàn)證，以便為該用戶訪問受保護(hù)的資源。對(duì)于API，讓客戶端收集用戶憑據(jù)以發(fā)送到您的服務(wù)器是一種不好的做法。這就是OAuth的用武之地

.OAuth提供了許多優(yōu)于第三方用戶名/密碼身份驗(yàn)證的優(yōu)勢(shì)。最重要的是，客戶端永遠(yuǎn)無法訪問用戶的憑據(jù)。用戶在登錄時(shí)會(huì)被重定向到您的服務(wù)器。用戶登錄到您的站點(diǎn)后，他或她將被重定向回客戶端，客戶端將在該客戶端接收訪問令牌，以便在將來對(duì)受保護(hù)資源的請(qǐng)求中使用。

使用OAuth的另一個(gè)重要好處是用戶可以隨時(shí)取消客戶端訪問。如果用戶因任何原因決定不再希望客戶端能夠代表他們?cè)L問受保護(hù)資源，他們只需轉(zhuǎn)到您創(chuàng)建的接口并取消客戶端的訪問權(quán)限。

盡早開始

使API成功的最重要的事情之一就是盡早開始。當(dāng)您編寫該函數(shù)以在數(shù)據(jù)庫中創(chuàng)建一些條目時(shí)，請(qǐng)繼續(xù)并花費(fèi)額外的時(shí)間并為其編寫API接口。

寫好文檔

沒有比沒有好的文檔更快地殺死API。雖然一些開發(fā)人員可以采用記錄不良的API并弄清楚它應(yīng)該如何工作，但大多數(shù)人都不愿意。

您應(yīng)該記錄您可用的每個(gè)API調(diào)用，并根據(jù)它們所處理的數(shù)據(jù)類型對(duì)API調(diào)用進(jìn)行分類。除了記錄API調(diào)用本身的端點(diǎn)外，還應(yīng)系統(tǒng)地定義必需和可選的輸入?yún)?shù)以及輸出數(shù)據(jù)結(jié)構(gòu)。輸入?yún)?shù)應(yīng)列出默認(rèn)值(如果有)，并指示預(yù)期的數(shù)據(jù)格式，如數(shù)字或字符串。最后，每個(gè)API調(diào)用都應(yīng)該有一個(gè)錯(cuò)誤條件和狀態(tài)代碼列表。

要完善您的文檔，請(qǐng)確保為每個(gè)API調(diào)用包含一個(gè)或兩個(gè)示例，以了解常見的輸入和輸出方案。

API開發(fā)：保持簡(jiǎn)單

盡管開發(fā)API似乎是一項(xiàng)復(fù)雜的工作，但API本身的概念并不是一個(gè)新概念，而且我們?cè)诖颂幱懻摰拿總€(gè)主題都有大量可用的文檔。只需確保在可以找到它們的地方使用良好實(shí)踐，并提供一致且記錄良好的界面。