[Proposal] Naming

Naming

• State: Draft
• Replaced by:
• Created:
• Tags:

Context

The two primary options are:

• ActionResource (for example, CreateBook)
• ResourceAction (for example, BookCreate)

With ResourceAction:

AccountCreate
AccountDelete
AccountGet
AccountSuspend
ApiTokenCreate
ApiTokenRefresh
ApiTokenRevoke

With ActionResource:

CreateAccount
CreateApiToken
DeleteAccount
GetAccount
RefreshApiToken
RevokeApiToken
SuspendAccount

Resolution

...

• Hacksoftware chose¹ the ResourceAction pattern.
• Google chose² the ActionResource pattern.

Footnotes

1. https://github.com/HackSoftware/Django-Styleguide?tab=readme-ov-file#naming-convention-1 ↩

2. https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0133.md#guidance ↩

[yordis]

Would this be for GraphQL, gRPC, JSON API? Regardless, my first immediate take is that, after so many years, I prefer to do ResourceAction so that things naturally stick to the proper grouping.

This reminds an issue from 2017 😭 graphql/graphql-spec#376

Would this be for GraphQL, gRPC, JSON API? Regardless, my first immediate take is that, after so many years, I prefer to do ResourceAction so that things naturally stick to the proper grouping.

This reminds an issue from 2017 😭 graphql/graphql-spec#376

Yeah, alphabetical sorting is handy for grouping API methods.

We could also use resource-specific services to handle that naturally. For example, resource-specific AdUnitService vs broader domain-based ChatService.

I haven't worked with GraphQL or JSON API, so can't really weigh in there 😭

With resource-specific services:

iam.example.com/
├── AccountService/
│   ├── create_account()
│   ├── delete_account()
│   ├── get_account()
│   └── suspend_account()
└── ApiTokenService/
    ├── create_api_token()
    ├── refresh_api_token()
    └── revoke_api_token()

[yordis]

This is a tricky subject, before we even get to the naming, we would need to agree on what "Resource" actually means AND after that what "Service" means.

It is not that obvious based on my experience.

Especially when Phyisical Boundaries and Logical Boundaries are ignored.

Lastly, I am trying to avoid creating yet another spec; so we are leaning on Google AIP as much as we can.

Sometimes, the names for request messages can become a little weird, for example SearchSearchAds360StreamRequest

The messages can also have super-duper-long names, for example VideoActionRecognitionPredictionInstance (this one is used indirectly though, under PredictRequest)

[yordis]

I do not like the fact that they aren't following something obvious: https://github.com/googleapis/googleapis/blob/3acfdb6166a7101691cdf812bf8f8a67a2084fde/google/ads/searchads360/v0/services/search_ads360_service.proto#L111-L129

Like [service name][rpc name][Request|Response] that is a very confusing name

That's the longest method name I've found -- UpdateSecurityHealthAnalyticsCustomModule

I do not like the fact that they aren't following something obvious: https://github.com/googleapis/googleapis/blob/3acfdb6166a7101691cdf812bf8f8a67a2084fde/google/ads/searchads360/v0/services/search_ads360_service.proto#L111-L129

Like [service name][rpc name][Request|Response] that is a very confusing name

Seems relevant: aip-dev/google.aip.dev#1085

[yordis]

Should be I feel adding Stream is a good idea, Streaming is long ... I do not see the point.

Some of those long names may be related to what I said before "Physical Boundaries and Logical Boundaries"

"Physically", you may want one port behind 1 service, but logically, that service has many resources ... so, you end up with such long naming.

You could create more "services" but may means multiple ports, sometimes, or other infra level stuff people dont want to deal with.

Assumptions. A lot of assumptions.

---

What I definitely do not support is doing Create or Update based on the service name, so always include the "resource" in the rpc, Create[x] or Update[x]