From a6f17066caf6e911b7e94e8feab52fa3af2def1b Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Mon, 15 Mar 2021 10:18:02 -0400 Subject: [PATCH] docs: Distinguish between public/private docs in 2.0 guide (#1226) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #1225 🦕 --- UPGRADING.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 475bd9f5e45..c3c9171ebf5 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -7,11 +7,24 @@ please continue to use version 1.x as we will continue supporting python 2.7+ in In addition, discovery documents will no longer be retrieved dynamically when you call `discovery.build()`. The discovery documents will instead be retrieved -from the client library directly. Existing code written for earlier versions of -this library will not require updating. We believe this new default behaviour -will provide a more predictable experience for users. If always using the latest -version of a service definition is more important than reliability, users should -set the `static_discovery` argument of `discovery.build()` to `False` to +from the client library directly. + +For users of public APIs +------------------------ +Existing code written for earlier versions of this library will not require +updating. We believe this new default behaviour will provide a more predictable +experience for users. If always using the latest version of a service definition +is more important than reliability, users should set the `static_discovery` +argument of `discovery.build()` to `False` to retrieve the service definition +from the internet. + +For users of private APIs +------------------------- +If the discovery document requires an authentication key to access it, the +discovery document is private and it will not be shipped with the library. +Only discovery documents listed in [this public directory](https://www.googleapis.com/discovery/v1/apis/) +are included in the library. Users of private APIs should set the +`static_discovery` argument of `discovery.build()` to `False` to continue to retrieve the service definition from the internet. If you experience issues or have questions, please file an [issue](https://github.com/googleapis/google-api-python-client/issues). @@ -27,7 +40,8 @@ to use version 2.0.0. **Note**: Existing code written for earlier versions of this library will not require updating. You should only update your code if always using the latest -version of a service definition is more important than reliability. +version of a service definition is more important than reliability or if you +are using an API which does not have a public discovery document. > **WARNING**: Breaking change