1 Why we need API design and documentation

來源：http://afoo.me/posts/2015-03-17-api-design-and-documentation.html
作者：隕石 - yunshi@wacai.com

HTTP API?（現(xiàn)在很多地方都使用REST API這個(gè)術(shù)語， 不過注意這里使用的是HTTP API，至于為什么， 嘿嘿，自己意會(huì)吧 ;-)?）?can't be typesafe as per the http protocol's essential， so we need to find a way so that the api providers and consumers can come to the same rendzvous point with proper constraits and clarity.

HTTP協(xié)議的特性決定了基于HTTP的API屬于松散類型（與強(qiáng)類型或者說類型安全的API相對(duì)應(yīng)）， 為了能夠讓API的提供者和消費(fèi)者可以一種雙方都可以明晰且明確的方式達(dá)成共識(shí)， 我們需要找到一種方式來描述API，以便對(duì)雙方進(jìn)行一定的約束，從而形成一種雙方都可以遵守的契約式的協(xié)議， 在某些層面增加少許工作量的同時(shí)，為雙方提供便利和參考。