Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add guidance to avoid overly generic resource names. #1288

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add guidance to avoid overly generic resource names. #1288

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8199fda
Add guidance to avoid overly generic resource names.
Jseph Dec 20, 2023
d852fa1
Added update description
Jseph Dec 20, 2023
67d1e36
Fix typo
Jseph Dec 20, 2023
fb4dce2
Add rationale and make suggested formatting changes
Jseph Dec 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion aip/general/0123.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@ the following pattern: `{Service Name}/{Type}`. The type name **must**:
- Be of the singular form of the noun.
- Use PascalCase (UpperCamelCase).

Additionally APIs **should** avoid overly generic resource names like
`Metadata`, `Resource`, `Config`, `Settings`, etc.

### Examples

Examples of resource types include:
Expand Down Expand Up @@ -108,6 +111,13 @@ proper name to use in code and documentation.
lowerCamelCase can be translated into other common forms of a resource name
such as UpperCamelCase and snake_case.

### 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.

Comment on lines +114 to +120
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

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.

<!-- prettier-ignore-start -->
[aip-122]: ./0122.md
[API Group]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups
Expand All @@ -118,7 +128,7 @@ such as UpperCamelCase and snake_case.
<!-- prettier-ignore-end -->

## Changelog

- **2023-12-20**: Added guidance on overly-generic resource type names.
- **2023-09-19**: Prohibit duplicate pattern variables.
- **2023-05-06**: Adding requirement of singular and plural.
- **2023-01-28**: Clarifying guidance for the resource type name.
Expand Down