问题描述
在寻找当前版本的 GitHub API 时发现，版本号似乎被省略了。他个人正在考虑在自己的 API 中添加一个新字段，但他想知道这是否是一种常见做法，或者应该采用其他方式。
解决方案
请注意以下操作注意版本差异及修改前做好备份。
方案1
许多 API 在服务的 URL 中包含版本号。以下是一些示例：
– https://api.twitter.com/1.1/statuses/home_timeline.json
– https://graph.facebook.com/v2.2/me/adaccounts
– https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
– https://maps.googleapis.com/maps/api/js?v=3.29
– https://westeurope.api.cognitive.microsoft.com/vision/v1.0/analyze
– https://www.europeana.eu/api/v2/opensearch.rss?searchTerms=Rembrandt
然而，互联网上的许多人认为这是不正确的，因为它违反了 REST/HTTP 规范；”将 API 版本嵌入到 URI 中会破坏超媒体作为应用程序状态引擎的概念”。更合适的做法是使用 Accept 头来请求特定版本。对于后者，人们建议使用供应商 MIME 类型，例如类似于 Accept: application/vnd.mycompany-api-v3+json。
尽管如此，许多 API 设计者包含 API 版本号在 URL 中的原因是因为它易于实现和调试（清楚地显示你正在使用的版本）。
附注：在我们的组织中，我们最近决定同时支持一个无版本的端点，始终指向我们 API 的最新稳定版本，以及一个带有版本规范的端点。这使用户可以选择是承诺使用我们的最新 API（可能需要在发布新版本时进行更改），还是连接到一个固定的 API 版本（随着时间的推移可能会被弃用）。