隨著業績蒸蒸日上,開始需要檢討既有 service APIs 的架構,以應付成長擴充的需要。但在動手術之前,必須先統一團隊成員的 API design 品質意識。所以,這又是我「讀書會」招數派上用場的時機了。此為其一。

幾位新人陸續報到,也需要一些訓練材料。此為其二。

於是,就有了這份閱讀清單。

由於時間限制,我只挑選能夠在四小時以內自行閱讀完畢、能夠在兩個小時以內集體討論完畢的素材。所以,這份閱讀清單,並不是最周全的,但應該足以闡述 "specification-driven development" 的觀點。

戴明說:「品質是內建的,不是檢驗出來的。」而 specification-driven development,抑或敏捷開發陣營常講的 definition of done 或 test-driven development,都是及早灌注 quality built-in 意識的重要手法。

儘早養成好習慣,可節省日後上窮碧落下黃泉大翻修的精力。



Part I / 基本觀念:程式語言層次

編程的頂尖對話》, pp.186—189 (Joshua Bloch 專訪)

演講 / How To Design A Good API and Why it Matters (by Joshua Bloch):

(選讀) 演講 / How to Design Great APIs (by Parse)



Part II / REST 觀念:Service 層次

Pure REST 古典定義:

(選讀) HATEOAS 101 - Opinionated Introduction to a REST API Style



Part III / "Pragmatic REST" 觀念

API Design, 2nd edition (by Apigee)

API Design, 3rd edition (by Apigee)



Part IV / 業界實例

演講 / API Design: When to buck the trend (Netflix API case study with Daniel Jacobson)



Part V / Spec-driven development 示例

(請先看觀念及流程,先不要聚焦在 RAML 細節上)

簡介 / Intro to RAML - API Spec Driven Development (by XDite)

Building Your API for Longevity

API Documentation Best Practices