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