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

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

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

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

始終如一

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

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

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

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

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

使用OAuth

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

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

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

盡早開始

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

寫好文檔

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

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

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

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

盡管開發(fā)API似乎是一項復(fù)雜的工作，但API本身的概念并不是一個新概念，而且我們在此處討論的每個主題都有大量可用的文檔。只需確保在可以找到它們的地方使用良好實踐，并提供一致且記錄良好的界面。