567
企業級API設計
最近對service的API設計，在team內有些討論，主要集中在API是足夠抽象、通用好呢， 還是具體、易用好？
其實這個是要折衷的，通用的好處是以後更改API的可能性小，但壞處是想要通用，裏麵的字段就不能定義太死，不定義死，極端的例子是全部用Name/Value Pair，最通用，但client麵對這些NV，根本不知道怎麼去設值，這樣的API很明顯是不友好，難用的，而一個好的API應該是自明的（self-documenting）的。 所以需要折衷。
關於API 通用性（Generic）和 自明性（self-documenting）討論繼續...
這個折衷要看應用場合，世界上最大的分布式係統是什麼？對，是萬維網，它的API是什麼，對，HTTP。 萬維網包羅萬象，所以其API（HTTP）要絕對的通用，可擴展。怎樣做到呢，沒有任何限製（constraint）的東西，無疑是最自由、最可擴展的，所以稍微知曉HTTP的同學，不難發現在HTTP裏，除了消息頭的元數據名如 HOST，Connection-type等是要遵循協議規範的（消息頭也是可擴展的，用戶可以自行添加頭部元數據，通常以X-開頭），對於消息體（Message Body）可以說是絕對的自由，沒有一丁點限製，你可以在裏麵放HTML，也可以是XML、JSON， 也可以是圖像，二進製流，音頻，視頻，可以說是世界上最通用的API。
再看一個場合，公司A和公司B合作，A需要提供一組API給B公司條用，好吧，B公司，我們決定使用世界上最通用的API給你用，www.A.com/service4B，可是裏麵的request body要怎麼寫呢？像這樣針對性不叫強的API，最好還是具體一點，這樣client看到你的接口，就基本知道要怎麼調用你的服務了, 比如對於查詢合同的API，你就必須要在HTTP Body裏寫明:
<contract>
<contractId>123456</contractId>
</contract>
或者用REST的思想，URI為 www.A.com/service4B/contract/123456. 這樣的API失去了通用性，但其專用性以及對特定環境下的約束，正是B公司我們想要的。
還有API也是一個不斷演化的過程，所以不用太擔心當前的API是不是擴展性太差，這也是Agile的思想，包括HTTP從1.0 到1.X 也是在不斷的演化當中。
當然一個企業級API需要考慮的因素還很多，這裏先開個頭，後麵會結合公司的CommerceOS （eBay next gen public API)，在詳細討論....
還有個原因就是，剛才看到一篇文章《管理企業級API的7個最佳實踐》，覺得說的還是很在理，先copy在這裏，後麵有時間再整理一下。
1. API優先的設計方法
SOA最佳實踐就是將API開發從後端應用中完全地分離出來。“與其在執行應用之後再創建API，倒不如先盡己所能提前創建好一個接口，然後再將其與後端邏輯相掛鉤。這樣一來，問題便可逐個擊破，開發者也可以更專注於清晰明了的API執行過程，而API測試也會變得更加容易。”Shafii如此說道。
2. 選擇一個穩定的API運行時
運行時的選擇可以說是至關重要。因此，我們必須要注意一個企業級API從創建開始的所有需求，比如可擴展性、實用性、可靠性等。即使API沒有進行修改，也應該能夠在企業內部和雲端順利運行。這樣一來，開發者便可以幹很多事情，比如利用雲來獲取更多額外資源，或者在充分準備之後，實現企業模型到雲模型的轉移等。
3. 創建一個中央服務存儲庫
另外一個關鍵點就是將API開放到一個中央存儲庫中，以便於開發者和終端用戶發現。
4. 通過版本、策略和契約來管理服務
對於任何操作係統或應用程序來說，API的版本控製都是必不可少的，其重要程度不亞於安全性和策略管理。
5. 提升和開放你的API
Shafii強烈建議為API創建一個社區平台，並為其提供信息和技術支持。
6. 通過度量、分析來監控和測量API使用情況
在商業活動中，評估力度越大，就越能有效追蹤到API的運行過程和結果。不管是從潛在的技術層麵還是商業層麵，一定的度量標準都會幫助開發者更好地了解API的使用情況。
7. 重構API以提升API用戶體驗和效率
對於這最後一點，Shafii更是反複強調，一定要對API保持不斷的更新。
最後更新：2017-04-03 16:49:04