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這個術(shù)語， 不過注意這里使用的是HTTP API，至于為什么， 嘿嘿，自己意會吧 ;-)?）?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屬于松散類型（與強類型或者說類型安全的API相對應）， 為了能夠讓API的提供者和消費者可以一種雙方都可以明晰且明確的方式達成共識， 我們需要找到一種方式來描述API，以便對雙方進行一定的約束，從而形成一種雙方都可以遵守的契約式的協(xié)議， 在某些層面增加少許工作量的同時，為雙方提供便利和參考。