Add guidance to avoid overly generic resource names.

[Jseph]

These often cause confusion down the line as the API introduces more concepts.

[noahdietz]

Can you also add a quick blurb in a Rationale sub-section? Something like ### Overly generic type names

[Jseph]

Added rationale as suggested.

[yordis]

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.