Moved over from #910 per @dhermes

Goal of this issue is to decide:

1. Is it reasonable to provide one-liners to do things like create_topic() which is just a wrapper:
   python def create_topic(self, name): topic = self.topic(name) topic.create() return topic
2. Can we agree on the naming convention of what does and does not require an API request

Comment from the pull request was...

The name create_topic is ambiguous to new users. Does it mean create a Topic instance or actual insert one?

That's a good point. I think we should adopt the attitude that client.<verb>_<noun>() is an API request. So create_topic would hit the API trying to 'insert' the topic (using Google's API lingo). client.<noun> is nothing more than a factory for the noun which won't fire an API request but gives you back an instance of the .

We'd need to offer Client.topic and Client.create_topic side-by-side since users would need to construct pre-existing topics without sending insert.

Totally agree -- I think we had this debate already and I'm totally sold on the need for .topic() as the sole way to get a hold of a topic object, without hitting the API (as the topic literally has zero extra metadata).

For other APIs, where the object itself holds lots of (potentially important) metadata, I think it might be worthwhile to provide a get_<noun>() to pull down that metadata, in addition to the <noun>() method which just gives you an object which may not be tied to the remote (authoritative) representation.

An example here might be bucket.

• .bucket() gives me a bucket object, sans remote data (no API request).
• create_bucket() explicitly creates the bucket in the remote service, throwing an error if I was unable to do so.
• get_bucket() would be an API request that gives me all the metadata about a bucket.

Note that the <verb>_bucket() methods are really just shortcuts so that I can have one-liners for the common things I want to do with a bucket. (ie, create == bucket = client.bucket('name'); bucket.create(); return bucket;)

In boto for S3, they have this verify or check parameter on the bucket constructor, so the comparisons look like:

I personally don't love the boto method, and would much rather the "gcloud (suggestion)" option.