谷歌中国开发者社区 (GDG)
  • 主页
  • 博客
    • Android
    • Design
    • GoogleCloud
    • GoogleMaps
    • GooglePlay
    • Web
  • 社区
    • 各地社区
    • 社区历史
    • GDG介绍
    • 社区通知
  • 视频
  • 资源
    • 资源汇总
    • 精选视频
    • 优酷频道

Versioning APIs at Google

2017-06-27adminGoogleCloudNo comments

By Dan Ciruli, Product Manager

Versioning APIs is difficult, and everyone in the API space has opinions about how to do it properly. It’s also almost impossible to avoid. As teams build new software, occasionally they need to get rid of a feature (or provide that feature in a different way). Versioning gives your API users a reliable way to understand semantic changes in the API. While some companies will go to great lengths to never change a version, we don’t have that luxury: with the number of APIs we operate, the number of teams developing them here and the number of developers relying on them, we version APIs so developers know what to expect from them.

Versioning APIs should be done according to a consistent and comprehensive policy. At Google, we follow the general principles of semantic versioning for our APIs. The principles behind semantic versioning are simple: each release gets a number, X and a number Y. X indicates a major version, and Y indicates a minor version. A new major version indicates a backward-incompatible change while a new minor version indicates a backward-compatible change.

Our major versions are reflected in the path of our APIs, immediately following the domain. Why? Well, it means that any API URL that you call will never rename or drop any of the fields you rely on. If you’re doing a GET on coolcloudapi.proxy.ustclug.org/v1/coolthings/12301221312132, you can rely on the fact that the JSON returned will never have fields renamed or removed.

There are pros and cons to this approach, of course, and many smart people have heated debates over the “right” way to version. Some people prefer encoding a version request in a header, others “keep track” of the version that any individual API consumer is used to getting. We’ve seen and heard them all, and collectively we’ve decided that, for our broad purposes, encoding the major version in the URL makes the most sense most of the time.

Note that the minor version is not encoded in the URL. That means that if we enhance the Cool Cloud API by adding a new field, you may one day be surprised when a call to coolcloudapi.proxy.ustclug.org/v1/coolthings/12301221312132 starts returning some additional data. But we’ll never “break” your app by removing fields.

When we release a new major version, we generally write a single backend that can handle both versions. All requests (regardless of version) are sent to the backend, and it uses the version in the path to decide which surface to return.

For customers using Cloud Endpoints, our API gateway, we’re starting to release the features that will enable you to follow these same versioning practices.

First, our proxy can now serve multiple versions of your API and reports the API version. This will let you see how much traffic different versions of your API receive. In practice, this means that you can tell how much of your traffic has migrated to a new version.

Second, it can give you a strategy for deprecating and turning down an API — by finding out who’s still using the old version. But that’s a topic for another blog post for another day.

Versioning is the thorn on the rose of making better APIs. We believe in the approach we’ve adopted internally, and are happy to share the best practices we’ve developed with the community. To get started with Cloud Endpoints, check out our 10-minute-quickstart or in-depth tutorials, or reach out to us on our Google Group at google-cloud-endpoints@googlegroups.com — we’d love to hear from you!



Source: Versioning APIs at Google

除非特别声明,此文章内容采用知识共享署名 3.0许可,代码示例采用Apache 2.0许可。更多细节请查看我们的服务条款。

Tags: AdWords

Related Articles

Falling Fruit helps urbanites forage for food using Google Maps Platform

2018-07-11admin

Container Engine now runs Kubernetes 1.7 to drive enterprise-ready secure hybrid workloads

2017-07-12admin

Puppet and Google Cloud Platform: a year in review

2017-12-15admin

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">

Recent Posts

  • Cloud Services Platform—bringing hybrid cloud to you
  • Setting a course to the future of cloud computing
  • Analyze this—expanding the power of your API data with new Apigee analytics features
  • Hello, .dev!
  • Google announces intent to acquire Alooma to simplify cloud migration

Recent Comments

  • Chen Zhixiang on Concurrent marking in V8
  • admin on 使用 Android Jetpack 加快应用开发速度
  • 怪盗kidou on 使用 Android Jetpack 加快应用开发速度
  • 鸿维 on Google 帐号登录 API 更新
  • admin on 推出 CVPR 2018 学习图像压缩挑战赛

Archives

  • February 2019
  • January 2019
  • December 2018
  • November 2018
  • October 2018
  • September 2018
  • August 2018
  • July 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • January 2018
  • December 2017
  • November 2017
  • October 2017
  • September 2017
  • August 2017
  • July 2017
  • June 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • January 1970

Categories

  • Android
  • Design
  • Firebase
  • GoogleCloud
  • GoogleDevFeeds
  • GoogleMaps
  • GooglePlay
  • Google动态
  • iOS
  • Uncategorized
  • VR
  • Web
  • WebMaster
  • 社区
  • 通知

Meta

  • Log in
  • Entries RSS
  • Comments RSS
  • WordPress.org

最新文章

  • Cloud Services Platform—bringing hybrid cloud to you
  • Setting a course to the future of cloud computing
  • Analyze this—expanding the power of your API data with new Apigee analytics features
  • Hello, .dev!
  • Google announces intent to acquire Alooma to simplify cloud migration
  • Google announces intent to acquire Alooma to simplify cloud migration
  • New UI tools and a richer creative canvas come to ARCore
  • Introducing PlaNet: A Deep Planning Network for Reinforcement Learning
  • AI in depth: monitoring home appliances from power readings with ML
  • AI in depth: monitoring home appliances from power readings with ML

最多查看

  • 谷歌招聘软件工程师 (21,032)
  • Google 推出的 31 套在线课程 (20,122)
  • 如何选择 compileSdkVersion, minSdkVersion 和 targetSdkVersion (18,720)
  • Seti UI 主题: 让你编辑器焕然一新 (12,686)
  • Android Studio 2.0 稳定版 (8,963)
  • Android N 最初预览版:开发者 API 和工具 (7,934)
  • 像 Sublime Text 一样使用 Chrome DevTools (5,949)
  • Google I/O 2016: Android 演讲视频汇总 (5,519)
  • 用 Google Cloud 打造你的私有免费 Git 仓库 (5,503)
  • 面向普通开发者的机器学习应用方案 (5,200)
  • 生还是死?Android 进程优先级详解 (4,971)
  • 面向 Web 开发者的 Sublime Text 插件 (4,140)
  • 适配 Android N 多窗口特性的 5 个要诀 (4,103)
  • 参加 Google I/O Extended,观看 I/O 直播,线下聚会! (3,476)
© 2018 中国谷歌开发者社区 - ChinaGDG