Use consistent "update" verbs in our API based on the underlying RPC (PUT/PATCH).

[aozarov]

When it comes to metadata, some apiary libraries provide "patch" operations, some provide "update" and others provide both.

In GCS API we picked the verb "update" for PATCH operation and we don't provide a "replace"/PUT
(which exists now in the apiary world but is probably going to be removed for gRPC).

I would like to avoid confusion when using different services, and suggests we always use the same
verb for metadata "patch" operations and a different one for metadata "replace" operations.

Some options for API names:

	Patch RPC	Update RPC
1	patch	update
2	patch	put
3	update	replace
4	update	set
5	update	put

Other options are welcomed.

gRPC does not provide the apiary level PATCH support (it is up to the service), and One Platform
suggests to use HTTP PATCH for update operations that are partial or non-idempotent.

My preference is option (3)

/cc @mziccard @ajkannan @jgeewax

[ajkannan]

Option 3 sounds good to me too.

For services that only provide one of the two (i.e. resource manager only has "replace"), should we create an "update" method and mimic the PATCH support if it makes sense?

[mziccard]

I'm for option (3) as well!

@ajkannan do you mean by getting a resource and then doing an update? I would avoid this as it might be inconsistent if the resource gets updated in the middle of the two calls.

[aozarov]

We actually can't mimic the apiary PATCH in cases when read-modify-write is not supported (so in resource manager you can do that for Policy but not for Project) and though One Platform seems
to be more lenient about it I suggest we do not do it.

I think we should expose what the service provides and pick our canonical name for it.

[ajkannan]

@mziccard @aozarov good points, I agree

[aozarov]

I think we all got into agreement and all actions were taken, right?
Can we close it? @mziccard @ajkannan

[ajkannan]

I made the appropriate changes in resource manager. In gcloud-java-datastore, we still use update instead of replace for entities. However, an Entity is slightly different than a metadata object like BlobInfo, Policy, and ProjectInfo; perhaps that distinction should be made clear in the docs somewhere?

[ajkannan]

Closing this issue since all necessary changes have been made.