Originally brought up: googleapis/google-cloud-node#1801 (comment)
google-cloud-node (GCN) has some conventions which ideally could be used here. It would be great to achieve a common UX that can be re-used by a developer when hopping between APIs.
Resource hierarchy
The GCN library layers its classes so that if you need a GCS "Object", for example, you go through 2 parent layers, the GCS class, and then a bucket:
var gcs = require('@google-cloud/storage')({authInfo});
var myBucket = gcs.bucket('my-bucket');
var myFile = myBucket.file('my-file');
myFile.getMetadata(function(err, metadata) {});
I can't speak for certain how this would look with the generated layer, but a simple interpretation would be something like:
var gcs = require('generated-storage-client')({authInfo});
gcs.getObject({
bucketName: 'my-bucket',
objectName: 'my-file'
}, function(err, resp) {});
The hierarchy used by GCN is nice because it lets you cache one resource that you intend to make multiple calls with; myFile.delete()
, myFile.createReadStream()
, etc.
Accessor methods
GCN distinguishes between two types of objects: a "Service" (Google Cloud Storage), and a "ServiceObject" (a Bucket). A consistent set of methods are exposed on a ServiceObject:
ServiceObject#create({ config options }, function(err, serviceObjectInstance, apiResponse) {})
ServiceObject#delete(function(err, apiResponse) {})
ServiceObject#exists(function(err, exists, apiResponse) {})
ServiceObject#get(function(err, serviceObjectInstance, apiResponse) {})
ServiceObject#getMetadata(function(err, metadata, apiResponse) {})
ServiceObject#setMetadata({ new metadata }, function(err, apiResponse) {})
*Methods that don't apply for a specific ServiceObject are removed, e.g. you can't delete a Compute Engine Region, but you can get its metadata.
Streaming methods / naming conventions
The upstream API has its own implementation of logical naming patterns, and in the generated layer, those probably shouldn't be tampered with. However, it might be appreciated by Node.js developers to recognize some names they know from other libraries, for example, createReadStream()
and createWriteStream()
where there are readable and writable streams.
In GCN's Bigtable API, we expose a createReadStream()
to access the proto service's "ReadRows" method.
We've also seen naming conflicts between JavaScript/Node.js definitions and the language-agnostic API terminology. Having a small handwritten map of convenience/conventional names to upstream names might be a big help.
// cc: @bjwatson @jgeewax @callmehiphop @jmdobry