Starting w/ Google Cloud Platform APIs
The “Missing Tutorials” series
Planning a small series of ‘getting started’ posts for those of you, like me, who may get to the point of wanting to write code against a Google service, having a language chosen but then, having not written code for a week or two, I’m stalled by “How exactly do I get started?”
As a Googler in Google Cloud, I use many of these Google Cloud Platform services and occasionally — though less frequently — other Google services. When I have my druthers, I’ll write as often as possible in Golang, Python, JavaScript (Node.js) and C# (Microsoft .NET). Some of my customers prefer me to write samples in Java. Truthfully, I’m (not yet) competent in PHP and Ruby but these round out the languages in which Google provides libraries and sample code. If I’m really good, I’ll use those last 2 in this series too :-)
Client Libraries… Let’s enumerate the ways
Google does a wonderful job in providing so-called API Client Libraries for *all* Google’s services for *all* the languages listed above. When Google exposes REST-based services through its public API infrastructure, the service is published to Google’s API Discovery Service and is described by a Discovery document. Client libraries for these services may be machine-generated from the Discovery documents.
This is powerful.
It means that, all being well, libraries in each of the languages is available concurrently with every version of every Google API. But wait, there’s more… there’s a second set of libraries and the rules are different.
For Google Cloud APIs (not *all* Google APIs), Google provides Cloud Client Libraries. For the Google Cloud APIs, you may use either (or both) types of library. For non-Cloud APIs, you may only use API Client Libraries. So, why two flavors?
I won’t duplicate this Google document’s content “Client Libraries Explained”. Suffice it to say that, if the Cloud Client Library is available for the language for the service(s) that you need, I recommend you use the Google Cloud Client Library.
There are 2 caveats to this advice:
- If you require consistency and will use multiple Google services (particularly non-Cloud services), because Cloud Client Libraries are not available in all languages for Cloud services and not available at all for non-Cloud services, you may need to use the API Client Libraries.
- If you require parity between Google’s APIs and the Libraries, you may find that the most-recent service functionality is not Generally Available (an important requirement for enterprise customers particularly) in the Cloud Client Libraries because these tend to lag the service. Whereas, with the API Client Libraries (thanks to machine-generation), there is no latency between service functionality and the functionality being surfaced in the libraries.
In the worrying case that I’ve merely exacerbated confusion, in my next posts, I’ll provide tangible examples for using both of the Libraries in each language. I’m not going to provide a singular example across all of them because that’s unlikely to benefit many of you. I will provide what I think are “missing tutorials” for anyone — like me — who would benefit from such getting started guides.
Before we begin, I’d like to introduce 2 tools that I encourage you to consider using.
Google API Explorer
https://developers.google.com/apis-explorer/Is very useful. It enables you to construct REST-based API calls against any version of any Google service. For example, let’s use it to create (insert) a Compute Engine instance.
The search bar provides autocomplete. Typing “compute” returns all the APIs prefixed “compute”. You can hit return to navigate results including “compute” or you can continue to filter the results by typing “.” and then, because in this case I know what I’m seeking, “instances.insert”:
There are 3 API versions that match this method. The current is “v1”. Once the version is selected, API Explorer provides a form, built using the service’s Discovery document, that can be used to invoke the service. Don’t forget to click the “Authorize requests using OAuth 2.0” slider in the upper right hand corner of Explorer.
Although API Explorer makes it easy to invoke service methods, it’s not always obvious what property and property values should be used. This is where the Google API documentation helps.
Google Docs
For all the Google services, API documentation is provided. From the previous example, a Google search for “Google Compute Engine API” will provide a link to the relevant documentation:
https://cloud.google.com/compute/docs/reference/latest/For each API version, the resources (e.g. “instances”) are listed and then the methods that are supported for each resource (e.g. “insert”):
https://cloud.google.com/compute/docs/reference/latest/instances/insertFrom this we can see how to complete the “Request body” for example in the API Explorer form:
https://cloud.google.com/compute/docs/reference/latest/instances/insert#request-bodyBecause of its utility, you should also see that API Explorer is embedded in a right hand pane of the API documentation for many Cloud services.
Application Default Credentials
Unless you have a strong reason not to do so, I recommend you write your code assuming Application Default Credentials (ADCs). As Google’s authorization mechanisms have evolved and Google’s Libraries have evolved, many solutions have been created to reduce the complexity securing your applications. ADCs represent the pinnacle of this process. It is trivial (really!) using ADCs to write code that correctly acquires auth credentials. As importantly, using ADCs means that your code will work (while you debug) on your local workstation, on App Engine, Compute Engine and Container Engine. Another case of, unless you have a compelling reasons *not* to, please default to using ADCs.
https://developers.google.com/identity/protocols/application-default-credentialsIf Java makes it this easy… !
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;GoogleCredential credential = GoogleCredential.getApplicationDefault();
Conclusion
Unless you’re developing using Google’s services every day or if you’re new to developing against Google services, the intention of this blog series is to provide some basic guidance for each of the languages for both the primary Library types to help you get started. Google, its services and the Libraries are all changing rapidly.
Hopefully the guidelines in this series will help you remain productive.
Let’s begin…