From dc6a5e9e1e96bdae04dc3cbe45b658b10ccb18c2 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 9 Jun 2023 12:05:53 +0100 Subject: [PATCH 1/3] Added a section on AIP scope 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. --- aip/general/0001.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/aip/general/0001.md b/aip/general/0001.md index 993996a2b1..2a1d9d2e55 100644 --- a/aip/general/0001.md +++ b/aip/general/0001.md @@ -28,6 +28,25 @@ serve as the source of truth for API-related documentation at Google and the means by which API teams discuss and come to consensus on API guidance. AIPs are maintained as Markdown files in the [AIP GitHub repository][]. +## Scope + +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 + 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 + 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 + 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 + remove that RPC. +- Is the API actually implementing an existing API specification that can't be + changed? If so, AIP conformance is impossible and should be deemed out of + scope. + ## Types of AIPs There are several different types of AIPs, described below. The list of AIP @@ -269,6 +288,7 @@ state, and will link to the new, current AIP. ## Changelog +- **2023-06-09**: Added section on the scope of AIPs. - **2023-05-10**: Updated names of current and editors and TLs. - **2019-07-30**: Further clarified AIP quorum requirements. - **2019-05-12**: Collapsed AIP approvers and editors into a single position, @@ -286,3 +306,4 @@ state, and will link to the new, current AIP. [@noahdietz]: https://github.com/noahdietz [@shwoodard]: https://github.com/shwoodard [@toumorokoshi]: https://github.com/toumorokoshi +[aip-122]: ./0141.md \ No newline at end of file From 675afb92badd87704b6a33d5eff6131de9c2431b Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Thu, 15 Jun 2023 10:44:40 +0100 Subject: [PATCH 2/3] Address review comment around non-Google APIs --- aip/general/0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/general/0001.md b/aip/general/0001.md index 2a1d9d2e55..b949bda579 100644 --- a/aip/general/0001.md +++ b/aip/general/0001.md @@ -30,8 +30,8 @@ are maintained as Markdown files in the [AIP GitHub repository][]. ## Scope -It doesn't make sense for *every* API to follow the AIPs - not even all -*Google* APIs. Some relevant factors to consider include: +It doesn't make sense for *every* Google API to follow the AIPs. Some relevant +factors to consider include: - 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 From 40524daff062f5f0c717375b716691444cc5b745 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Wed, 5 Jul 2023 12:19:03 +0100 Subject: [PATCH 3/3] Added examples of third party APIs --- aip/general/0001.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/aip/general/0001.md b/aip/general/0001.md index b949bda579..dbef8b93e0 100644 --- a/aip/general/0001.md +++ b/aip/general/0001.md @@ -45,7 +45,9 @@ factors to consider include: remove that RPC. - Is the API actually implementing an existing API specification that can't be changed? If so, AIP conformance is impossible and should be deemed out of - scope. + scope. Some such APIs may be REST-like but not follow AIP conventions (package + management APIs often fall into this category); others may not be HTTP-based + at all (e.g. ssh or database protocols). ## Types of AIPs