[[333102]]

【51CTO.com快譯】本文將從SDK與文檔的使用，向后兼容性的保持，處置升級，有效地開展測試這五個方面，與您討論REST API設計的各項實踐。

毋庸置疑，API已成為了當前在不同系統之間交換信息的實際標準。它往往能夠有助于更好地集成某個系統內部各種組件。那么怎樣才能設計出更好的API呢?在本文中，我將和您討論在進行多種REST API設計和實現時，那些值得遵循的良好實踐原則。

1.善用各種客戶端SDK，而無需自行編寫代碼

如果服務提供商或創建者已經給出了一套開發工具包(SDK)，那么我們就應該在API調用中使用它們，而無需在本機REST調用之上，去重新編寫自己的客戶端庫。此方面的一個最好例子便是與Amazon Web Services交互的AWS SDK。選擇使用AWS SDK，不但有助于減緩的團隊學習曲線、快速上手，而且能夠節省編寫有關安全性、網絡超時、重試、回退等邏輯事務處理的時間。

此外，由于這些SDK由提供商所維護，因此開發人員無需進行繁瑣的測試、修復和更改，即可支持各種新的API節點。如今，大多數SDK不但開源，并且能夠支持和快速集成包括REST、WebSocket、以及gRPC在內的各種標準協議。

不過，API SDK的主要缺點是：可用性，以及對您所選編程語言的支持程度。針對此類狀況，開發人員有時需要開發自定義的REST客戶端。在此，我的經驗是：開發人員應將其設計和實現作為一個單獨的Maven項目，托管到企業Git存儲庫中，并配上充分的文檔記錄，以供組織中的所有內部團隊共享使用。

2.巧用文檔

上文提到的配套文檔，不但對API開發人員，尤其是那些沒有任何開發背景的人員而言，是著手開發的基本要素，而且文檔往往也是絕大多數現代化開發框架的一個不可或缺的部分。作為開發人員的我，經常可以根據現有的文檔，來輕松地執行與API相關的各項測試，而不必臨時到浩如煙海的社區或論壇上，去搜索相關資料。通常，API的相關文檔能夠向使用者介紹API的基本功能、各種參數、以及預期的負載(payload)模型。

當然，我在參與各種項目中也發現，有些文檔雖然包含了詳盡的內容(包括負載模型的范例)，但是其中有些已經滯后于API的當前版本。因此，我在項目中往往會使用Swagger將文件的方法、參數和模型緊密地集成到服務器端的代碼之中，讓客戶端和文件系統的服務器以同樣的速度來更新與同步。

3.遵循標準的端點方法

在設計API時，許多開發人員不但容易忽略端點的標準命名法則，而且并未按照HTTP的各種動詞定義進行操作。關于此方面的資料，網上有許多，只要你愿意花時間搜，一定能找到不少。下面，我分享一下自己一直嚴格遵守，同時也要求部門內開發人員持續遵循的幾種方法：

• 不要在端點中混合使用大、小寫字母。例如：請將“/users/userId”更改為“/users/{id}”。請把POST“/deleteUser/userId”代替為DELETE“users/{id}”。
• 始終在URL中使用版本控制，例如：我會將“/api/v1/”作為URL的必要組成部分。
• 將“https”作為客戶端連接的默認選項。
• 請將負載驗證組件作為代碼處置的第一步。千萬不可將其留到后期處理，甚至是留給異常捕獲程序去處理。

4.處置升級

我曾經遇到過這樣的一個案例：我們的某項服務一直使用著某個API來傳遞一些數據，但是某天它突然不工作了。在經過了多輪電子郵件和電話會議的討論與研究后，我們最終才發現是因為該API的負載發生了變化--增加了一個必填字段。然而，我們在對該API的升級過程中，沒有考慮到向后兼容這個問題!

為了避免此類錯誤，我們應當使用現有的CI(持續集成)流程，以盡早地檢測出來。而作為一名API開發人員，您在更改目標API的時候，應該充分考慮現有的客戶端。例如：在請求的正文中，那些新的字段，是應該使用默認值呢?還是應該定義一個諸如“/api/v2”之類的新版本端點?

5.測試

此處說所的測試，不只是功能性測試，也包括負載測試。您應該能夠獲悉目標服務器每分鐘通常可以處理多少個API調用，以及在網絡延遲增加時，響應時間會產生何種變化。如今，更多的企業會在全球范圍內部署不同規模的數據中心，或是采用多區域的云端環境。例如：我們有必要了解到，您在美國西部托管的API服務器，是否能夠給那些來自美國東部、歐洲、澳洲、甚至是亞洲的客戶端實例請求，提供足夠的帶寬和連接數。

就我的個人經驗而言，我更喜歡使用諸如：Postman或Apache JMeter之類的API測試工具，而不是從零開始編寫工具與用例。它們不僅能夠為我節省時間，還能夠方便我輕松地check-in到git，并且導出各種模板。

總結

上述五點經驗，便是我在實際項目中有關設計REST API的個人總結。希望它們能夠為您的API開發，以及軟件工程的其他方面，帶來一些啟發，讓你少走一些彎路。

【原標題】5 Tips for Better REST API Design

 作者: Preetdeep Kumar

【51CTO譯稿，合作站點轉載請注明原文譯者和出處為51CTO.com】