Contract, Interface, and API Document

有一些程式經驗的人大多聽過 design by contract 這個詞，意思大致是按照 contract 實作；部份習慣於 object-oriented programming 的人很自然的就把 contract 誤以為等價於 interface，中了 interface-as-contract myth [1]。

Interface 跟 contract 最大的差別在於：interface 是純粹的介面，不涉及實作後的行為，也就是說按照 interface 實作的 client code，只確保能呼叫得到，不能確保呼叫後的行為是否符合預期；但是 contract 是包括 precondition 與 postcondition，比 interface 更進一步限制了實作行為。

但這也並不代表 contract 就能完全涵蓋 interface，主要因為 contract 通常並不涉及實作的語言；例如 interface 可以指定 method arguments 的順序跟型別，但這些通常不會涵蓋在 contract 裡頭。也因此當我們談 test code generation 時，interface 扮演主要角色，而 contract 則在 test case (input/output) generation 扮演主要角色。

最後是 API document ...
API document 主要目的是讓編寫 client code 的人能正確地產生參數呼叫 API，目的在於彌補 interface 的不足，一般會先解釋一下這個 API 的用途，加註各個參數 domain 上的意義而不單只是型別，另外也會描述拋出例外的情況等；因此就意義上偏向 contract 更多一點，但又比 contract 多依賴了特定 programming language 或 protocol 等；甚至可以包括所有 contract 的資訊形成 API contract。

近年來因為 microservice architecture 的大量興起，讓 Web API 又受到重視，許多 interface description language (IDL), API description language, API documentation language 也相繼產生，釐清上面三個的角色跟功能，可以幫助我們回頭檢視這些 description languages 應該有的功能跟後續自動化的可能。


see also:
[1] API Design Myth: Interface as Contract
[2] An API Definition As The Truth In The API Contract
[3] Design by Contract