Add guidance to avoid overly generic resource names. #1288
Conversation
These often cause confusion down the line as the API introduces more concepts.
Note: the date will need to be updated if this is merged.
noahdietz
requested review from
andrei-scripniciuc
and removed request for
itsStrobe
|
Added rationale as suggested. |
| ### Overly Generic Type Names | ||
|
|
||
| Overly generic types like `Metadata` or `Resource` will cause confusion as the | ||
| API introduces more concepts. Unless the resource represents a | ||
| [singleton][aip-156] containing API-level settings, a more specific name should | ||
| be used. | ||
|
|
There was a problem hiding this comment.
In light of the recent guidance to avoid generic resource names,
I recommend providing developers with specific naming conventions for common patterns. For instance, patterns where information is passed as a 'bag' of data, often seen in APIs like:
- https://stripe.com/docs/api/metadata
- Pass through transient data to webhooks on registration ory/kratos#3102
These patterns typically involve attaching transient(depending of the workflow) data to a resource or tagging for message-passing and webhook consumption. I've encountered this frequently and concur that a standardized terminology would be beneficial. Specifically, distinguishing between two levels of metadata can be crucial:
- System Metadata: This level is intended for developers and controls system-level workflows. Only programmers should attach data to these objects based on Internal concerns to the service that defined.
- User-Level Metadata: Allows external clients to append information, enabling control over the flow not just internally but also for client-side processes.
By adopting distinct terms for these levels, we can reduce confusion and enhance the clarity and functionality of our API designs.
I would love to hear your thoughts about the topic and how Google thinks about it.
These often cause confusion down the line as the API introduces more concepts.