Change should to must for Resources#926
Conversation
For Resources, APIs must provide Get and otherwise should. An example is provided for when an API might not provide a Get.
| from a single resource. | ||
| APIs **must** provide a `Get` method *for resources* and **should** do so otherwise, | ||
| unless there is a strong reason not to do so. An example of such, would be if there | ||
| is sensitive data that would be included in the response. The purpose of the `Get` method |
There was a problem hiding this comment.
Are we capitalizing get?
There was a problem hiding this comment.
I prefer it as long as it has backticks. It is a proper thing, imho.
There was a problem hiding this comment.
Precedent AFAICT is "Get" and "get". I think we should try to always use Get in AIPs to make it explicit that we're talking about a method. In aipdesignbook I try to use "Get" throughout to clarify.
| APIs **should** generally provide a get method for resources unless it is not | ||
| valuable for users to do so. The purpose of the get method is to return data | ||
| from a single resource. | ||
| APIs **must** provide a `Get` method *for resources* and **should** do so otherwise, |
There was a problem hiding this comment.
I am not sure if this is clear.
I am guessing the intent here is to enforce existence of get unless justified otherwise.
As in: "do not leave this field blank" Either implement or justify why not. Right?
There was a problem hiding this comment.
Is it a field or an rpc?
There was a problem hiding this comment.
Reasons to not provide a Get method cannot not be open-ended. There must be a specified set of permitted exceptions and specific guidance regarding what to do for each exceptional case instead.
There was a problem hiding this comment.
I'm confused by this wording also.... It sounds like we're saying "You must unless ", which is not what "must" means... We copy RFC-2119 (as stated in AIP-8), so if we're going to make this must, there can be no exceptions. If we want exceptions, this must remain as "should". I also agree it should be should.
Assuming that it remains "should", I agree with @bgrant0607 that we should be explicit about guidance for not providing a Get method. Do we have a list of those cases? If not, we might have to leave it ambiguous and circle back with a list of specific exceptions based on our experience.
There was a problem hiding this comment.
The omission of Get from https://google.aip.dev/128 was an oversight. We could constrain "must" to declarative-friendly APIs.
Are there legitimate cases for not providing Get of a resource, at least for new services? Good question. I'm not aware of any offhand.
One case that comes up is resources containing sensitive data. However, sensitive user data really should not be represented in resource attributes. Resources ideally should be considered non-sensitive "metadata" rather than user data. Sensitive user data belongs in an appropriate storage system like a secret manager.
Other cases I'm aware of require performing a List, then extracting the specific resource in the client. We should definitely recommend against that.
There was a problem hiding this comment.
Are there legitimate cases for not providing Get of a resource, at least for new services? Good question. I'm not aware of any offhand.
I also don't have one on the top of my head, but I can say for sure there have been scenarios where this came up, and I recall thinking "OK yea, that makes sense. Go ahead."
There was a problem hiding this comment.
The 2 cases I mentioned were the ones I've seen. I would include both and indicate what the recommended alternatives are.
@loudej has thoughts also
|
cc @loudej |
| APIs **should** generally provide a get method for resources unless it is not | ||
| valuable for users to do so. The purpose of the get method is to return data | ||
| from a single resource. | ||
| APIs **must** provide a `Get` method *for resources* and **should** do so otherwise, |
There was a problem hiding this comment.
I'm confused by this wording also.... It sounds like we're saying "You must unless ", which is not what "must" means... We copy RFC-2119 (as stated in AIP-8), so if we're going to make this must, there can be no exceptions. If we want exceptions, this must remain as "should". I also agree it should be should.
Assuming that it remains "should", I agree with @bgrant0607 that we should be explicit about guidance for not providing a Get method. Do we have a list of those cases? If not, we might have to leave it ambiguous and circle back with a list of specific exceptions based on our experience.
| from a single resource. | ||
| APIs **must** provide a `Get` method *for resources* and **should** do so otherwise, | ||
| unless there is a strong reason not to do so. An example of such, would be if there | ||
| is sensitive data that would be included in the response. The purpose of the `Get` method |
There was a problem hiding this comment.
Precedent AFAICT is "Get" and "get". I think we should try to always use Get in AIPs to make it explicit that we're talking about a method. In aipdesignbook I try to use "Get" throughout to clarify.
4 participants
Change to AIP 131
This change indicates that, for Resources, APIs must provide
Getand otherwise should. An example is provided for when an API might not provide a Get.