制定版本并在版本之間平緩過渡對于設(shè)計和維護一套 API 是個巨大的挑戰(zhàn)。所以,最好在設(shè)計之初就使用一些方法來預(yù)防可能會遇到的問題。
為了避免 API 的變動導(dǎo)致用戶使用中產(chǎn)生意外結(jié)果或調(diào)用失敗,最好強制要求所有訪問都需要指定版本號。請避免提供默認版本號,一旦提供,日后想要修改它會相當困難。
最適合放置版本號的位置是頭信息(HTTP Headers),在 Accept
段中使用自定義類型(content type)與其他元數(shù)據(jù)(metadata)一起提交。例如:
Accept: application/vnd.heroku+json; version=3