Database Reference
In-Depth Information
Discovering Google APIs
There is an advantage, however, that SOAP has over REST APIs. Although
REST APIs are often easier to develop intuition about, there is no common
description language for them. SOAP APIs, on the other hand, have a
well-defined XML description that can tell you everything you need to know
to call the API.
Google attempts to bridge this gap in API description via the discovery page.
If you navigate your web browser to
https://www.googleapis.com/
discovery/v1/apis/bigquery/v2/rest
, you can find the discovery
document for the BigQuery API. In fact, if you read and understand this
page, much of the rest of this chapter will be redundant. (Although hopefully
you'll find the rest of the chapter more interesting than 2000 lines of JSON.)
Unlike this topic, however, the discovery document is designed to be read
by programs, not necessarily by humans. That said, it is easy for humans
to understand it, since one of the principles of REST is human-readability.
Official documentation can sometimes be missing or out of date, but the
discovery document is the actual definition of the API, and as such, it is
always up to date. It can be useful if you want to read about the different
arguments to various API calls or to find out what various fields mean. For
example, near the top of the discovery document is a section that looks like:
"prettyPrint": {
"type": "boolean",
"description": "Returns response with indentations
and line breaks.",
"default": "true",
"location": "query"
},
This snippet tells you about an undocumented feature: that you can add
prettyPrint=true
to the query portion (that is, the part after the
?
) of
any BigQuery URL, and it will cause the response to be returned in a format
that is easier for humans to read (as opposed to more compact, which is
easier for computers to read and more efficient to transmit).
The description of the API in the discovery document is rich enough to
enable automatic generation of client libraries in a variety of programming
languages.
The
page
at
