Discovery API should either work with version=None or raise an exception

[DFrenkel]

Background

Google API Discovery V2 supports not supplying the version: for example, this URI happily returns what looks like the latest version of the service discovery document.

Requesting specific service version in discovery is probably a more common case (correct me if I am wrong here), but it comes with some maintenance cost: when a version of the service gets deprecated, customers have to explicitly move to another version when making discovery.build() calls.

Passing version=None to discovery.build(), having the intent to always get the latest version of the discovery document, results in a Bad Request errors because by default we prefer discovery v1, which does not support "default" or "latest" version semantics:

>>> from googleapiclient.discovery import build
>>> build("cloudresourcemanager", version=None)
Traceback (most recent call last):
...
googleapiclient.errors.HttpError: 
<HttpError 400 when requesting https://www.googleapis.com/discovery/v1/apis/cloudresourcemanager//rest
returned "Request contains an invalid argument.">

However, this works just fine:

>>> from googleapiclient.discovery import V2_DISCOVERY_URI
>>> build("cloudresourcemanager", version=None, discoveryServiceUrl=V2_DISCOVERY_URI)
...<googleapiclient.discovery.Resource object at 0x109986160>

This means that while we could fail over to the V2 discovery, we don't. We should probably correct this behavior in one of the two ways I am proposing below.

Proposal

Choice 1:

• When version is not None, keep the order of discovery as is (i.e. V1 first, then V2 if V1 returns 404)
• When version is None, drop V1 discovery (we know it will return an error) and only use V2, with logging a warning, something like Not providing specific service version during discovery may result in unexpected failures due to backwards compatibility

Choice 2:

• Just raise an exception if we believe version is required during discovery and None is passed in.