diff --git a/aip/general/0001.md b/aip/general/0001.md index 993996a2b1..dbef8b93e0 100644 --- a/aip/general/0001.md +++ b/aip/general/0001.md @@ -28,6 +28,27 @@ 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* 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 + 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. 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 There are several different types of AIPs, described below. The list of AIP @@ -269,6 +290,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 +308,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