Added a section on AIP scope #1130

jskeet · 2023-06-09T11:19:49Z

Effectively, not all parts of all AIPs are relevant to all APIs. This section gives some examples of other considerations, although it's not intended to be exhaustive.

toumorokoshi

Thanks for starting this! I think we should do some more refining of the specific cases that are believed to be exceptional, and making sure that guidance is crystal clear to consumers.

I left a few comments so we can go back and forth on this.

aip/general/0001.md

toumorokoshi · 2023-06-09T15:52:56Z

aip/general/0001.md

+It doesn't make sense for *every* API to follow the AIPs - not even all
+*Google* APIs. Some relevant factors to consider include:
+
+- Who is writing code to call the APIs? Some AIPs (e.g. [141](AIP-141)) include


I think the wording of this section could be more succinct, with a clear litmus test of when the guidance applies or does not apply. We should use RFC-2119 must/should/should not to help clarify.

This section reads more like a conversation, which does not fit the style of the rest of the AIPs (which are itemized discrete guidance, sometimes with rationale attached).

toumorokoshi · 2023-06-09T15:54:41Z

aip/general/0001.md

+- Who is writing code to call the APIs? Some AIPs (e.g. [141](AIP-141)) include
+  requirements with an expectation of APIs being called from client libraries
+  written in diverse programming languages. If the API producer is confident
+  that the API only needs to be called from Google-authored code, some of those


This wording is kind of vague and puts a lot of control in the hands of the API producer. This isn't really the case - despite the API producer's perspective, for example, Cloud has strict requirements for coverage in our clients to meet demand of our larger customers.

I think this goes back to my larger point about this section enumerating clear exceptional cases that allow a reader to easily bucket their APIs into a relevant category. There is always the fallback of reaching out to API design for questions.

This isn't really the case - despite the API producer's perspective, for example, Cloud has strict requirements for coverage in our clients to meet demand of our larger customers.

Except there are Cloud APIs which do fall into this category. Annoyingly, I had an example of this just the other day... will try to find it.

Got it! Googlers, see b/217611342 for an example.

taking a brief look at the issue, I'd wonder if that's a classification issue.

Nevertheless I'm a bit concerned that there's statements in the AIPs that put a lot of control of which rules they follow in the AIP itself.

Maybe we can take this conversation offline? we won't resolve it offline I imagine.

We have some AIPs with specific scope, such as Cloud AIPs. It seems like we should refer to those categories.

toumorokoshi · 2023-06-09T15:56:14Z

aip/general/0001.md

+- How is the client code deployed? When the set of deployed clients is fully
+  known and fully controlled (most importantly for server-to-server APIs), many
+  requirements around compatibility can be skipped. For example, if you
+  *absolutely know* that no code exists that will call an RPC, it's safe to


I feel like this particular point would be better put into the backwards compatibility AIP. I've seen a few cases where this type of guidance pops up outside of the main AIP, and as a result it leads to only one section being edited and readers finding contradictions.

+1. I would put it in a section on deprecation/removal.

How about I move (and expand) details to the compatibility AIP, but link to it from here as an example of how context matters?

definitely! I 100% support linking to give people a place to read more, but not duplicating guidance.

toumorokoshi · 2023-06-09T16:07:11Z

aip/general/0001.md

+  that the API only needs to be called from Google-authored code, some of those
+  requirements may not be relevant.
+- How is the client code deployed? When the set of deployed clients is fully
+  known and fully controlled (most importantly for server-to-server APIs), many


this is too vague, in my opinion: it's not clear what cases are exceptional, and I don't think service producers would know either.

I'm not confident that we should imply this level of freedom in adhering to the AIPs: there is significant value to Google overall in adhering to them.

It would be better to enumerate specific broader where non-adherence is acceptable (e.g. specific external API specifications that must be adhered to) and let ambiguity lead to dialogue instead.

+1. I have no idea what case(s) this is alluding to.

It's really for code which never leaves Google's own data centers - purely internal code where we always know what API versions callers are using. We suggest that internal APIs follow AIPs, but that makes a huge difference in terms of compatibility requirements.

Ah, such as when all clients are in the monorepo?

Yes, exactly that. (Or even if they're in multiple repos but it's a well-known and complete set of repos, it's still controllable.)

bgrant0607 · 2023-06-09T21:36:50Z

aip/general/0001.md

+- Who is writing code to call the APIs? Some AIPs (e.g. [141](AIP-141)) include
+  requirements with an expectation of APIs being called from client libraries
+  written in diverse programming languages. If the API producer is confident
+  that the API only needs to be called from Google-authored code, some of those


Is this referring to non-public APIs?

We have some APIs which are public, but not actually intended to be called by non-Google code. (In those cases the protos are published but we typically don't generate client libraries.)

Ah, such as undocumented APIs purely for our web and mobile clients?

Those would count as internal (I think) and not published. There are some that are expected to be called by agent processes on customers' GKE projects, as a slightly different example. I wish I had all the examples I've seen to hand...

aip/general/0001.md

bgrant0607 · 2023-06-09T21:40:40Z

aip/general/0001.md

+  that the API only needs to be called from Google-authored code, some of those
+  requirements may not be relevant.
+- How is the client code deployed? When the set of deployed clients is fully
+  known and fully controlled (most importantly for server-to-server APIs), many


+1. I have no idea what case(s) this is alluding to.

bgrant0607 · 2023-06-09T21:41:37Z

aip/general/0001.md

+- How is the client code deployed? When the set of deployed clients is fully
+  known and fully controlled (most importantly for server-to-server APIs), many
+  requirements around compatibility can be skipped. For example, if you
+  *absolutely know* that no code exists that will call an RPC, it's safe to


+1. I would put it in a section on deprecation/removal.

jskeet · 2023-07-05T11:20:04Z

Ping for more responses to comments, @toumorokoshi and @bgrant0607. (If we've gone off the idea of this PR at all, that's fine too. I'd just like to make progress in some sense.)

toumorokoshi · 2023-07-07T23:26:10Z

Thanks! I left a couple more comments.

I think there's just high-level philosophical agreement in some places - let's get that ironed out offline and we can round back here.

There is definitely still value in defining the scope of AIPs. especially those that must adhere to other third-party specifications.

bgrant0607 · 2023-07-07T23:51:47Z

aip/general/0001.md


+## Scope
+
+It doesn't make sense for *every* Google API to follow the AIPs. Some relevant


It may help to start with base assumptions about what types of APIs the AIPs are for: public APIs with a wide variety of external clients (examples are in https://google.aip.dev/9#client).

toumorokoshi · 2023-07-13T19:29:08Z

Copying some high-level notes from the meeting today. We agree upon the following and doing some smaller changes to address the following:

Backwards compatibility: if you have complete control of your clients, then a lot of the concerns in the compatibility AIPs go away.
AIPs are Intended for public APIs, although private APIs (e.g. CorpEng) can adhere to them to leverage common tooling and clients.
Existing third party APIs that become Google APIs via acquisition are out of scope until they write a new AIP-compliant API.
APIs that adhere to a third party specification are out of scope.

Added a section on AIP scope

dc6a5e9

Effectively, not all parts of all AIPs are relevant to all APIs. This section gives some examples of other considerations, although it's not intended to be exhaustive.

jskeet requested a review from a team as a code owner June 9, 2023 11:19

toumorokoshi suggested changes Jun 9, 2023

View reviewed changes

bgrant0607 reviewed Jun 9, 2023

View reviewed changes

Address review comment around non-Google APIs

675afb9

toumorokoshi mentioned this pull request Jun 26, 2023

Define scope of the google AIPs #1151

Open

Added examples of third party APIs

40524da

bgrant0607 reviewed Jul 7, 2023

View reviewed changes

jskeet mentioned this pull request Jul 26, 2023

Clarify scope of compatibility rules. #1187

Merged


		## Scope

		It doesn't make sense for every Google API to follow the AIPs. Some relevant

Added a section on AIP scope #1130

Are you sure you want to change the base?

Added a section on AIP scope #1130

Uh oh!

Conversation

jskeet commented Jun 9, 2023

Uh oh!

toumorokoshi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jskeet commented Jul 5, 2023

Uh oh!

toumorokoshi commented Jul 7, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toumorokoshi commented Jul 13, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants