Frequently asked questions

<!DOCTYPE html> <html lang="en-US" class="glue-flexbox"> <head> <title>Frequently asked questions</title> <meta charset='utf-8'> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width,maximum-scale=2"> <link href="//fonts.googleapis.com/css?family=Roboto:100,300,400,500,700|Google+Sans:400,500|Product+Sans:400&lang=en" rel="stylesheet"></link> <link rel="shortcut icon" href="/assets/favicon.ico"> <link rel="stylesheet" type="text/css" media="screen" href="//www.gstatic.com/glue/v22_1/glue.min.css"> <link rel="stylesheet" type="text/css" media="screen" href="/assets/css/style.css?v=26220397"> <link rel="stylesheet" type="text/css" media="print" href="/assets/css/print.css?v=26220397"> <script type="text/javascript" src="//code.jquery.com/jquery-3.4.0.min.js"></script> <script type="text/javascript" src="//www.gstatic.com/glue/latest/glue-detect.min.js"></script> <script type="text/javascript"> $('html').css('visibility', 'hidden'); $.when($.ready).then(() => { $('html').css('visibility', 'visible'); }); </script> <script type="text/javascript" src="/assets/js/global.js?v=26220397"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-140054909-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-140054909-1'); </script> </head> <body>  <header class="glue-header glue-header--single"> <div class="glue-header__bar glue-header__bar--desktop glue-header__drawer"> <div class="glue-header__tier">  <div class="glue-header__container"> <div class="glue-header__lock-up"> <div class="glue-header__logo"> <a class="glue-header__logo-link" href="/" title="Google"> <div class="glue-header__logo-container"> <svg role="img" aria-hidden="true" class="glue-header__logo-svg"> <use xlink:href="/assets/images/glue-icons.svg#google-color-logo"></use> </svg> </div> <p class="glue-header__logo--product">AIPs</p> </a> </div> <a href="#page-content" class="glue-header__skip-content"> <p class="glue-header__skip-content-text">Jump to Content</p> </a> </div> </div>  <div class="glue-header__container glue-header__container--flex-auto"> <nav class="glue-header__link-bar"> <ul id="list-1" class="glue-header__list"> <li class="glue-header__item"> <a class="glue-header__link" href="/general" aria-level="1">Browse AIPs</a> </li> <li class="glue-header__item"> <a class="glue-header__link" href="/news" aria-level="1">News</a> </li> <li class="glue-header__item glue-header--is-active"> <a class="glue-header__link" href="/faq" aria-level="1">FAQ</a> </li> <li class="glue-header__item"> <a class="glue-header__link" href="/contributing" aria-level="1">Contributing</a> </li> <li class="glue-header__item"> <a class="glue-header__link" href="https://linter.aip.dev/" target="_blank" aria-level="1"> API Linter <svg role="img" class="glue-icon glue-icon--18px"> <use xlink:href="/assets/images/glue-icons.svg#open-in-new"></use> </svg> </a> </li> </ul> </nav> </div>  <div class="glue-header__container glue-header__container--cta"> <div class="glue-header__cta"> <div class="glue-sitesearch"> <form method="GET" action="/search"> <label for="q">Search this site</label> <input class="glue-sitesearch__input" type="text" name="q" id="q" placeholder="Search AIPs"> <button type="submit" class="glue-button glue-sitesearch__submit" title="Submit"> <svg role="img" class="glue-icon glue-icon--24px"> <use xlink:href="/assets/images/glue-icons.svg#search"></use> </svg> </button> </form> </div> <a href="https://github.com/aip-dev/google.aip.dev" target="_blank" class="glue-button glue-button--high-emphasis"> <img src="/assets/images/github.png" class="github-logo"> View on GitHub </a> </div> </div> </div> </div>  <div class="glue-header__bar glue-header__bar--mobile"> <div class="glue-header__tier">  <div class="glue-header__container"> <div class="glue-header__lock-up"> <div class="glue-header__hamburger glue-header__hamburger--first-tier"> <div class="glue-header__hamburger-wrapper"> <button type="button" class="glue-header__drawer-toggle-btn" aria-controls="drawer" aria-expanded="false" aria-label="Open the navigation drawer"> <svg role="img" class="glue-icon glue-icon--24px"><use xlink:href="/assets/images/glue-icons.svg#menu"></use></svg> </button> </div> </div> <div class="glue-header__logo"> <a class="glue-header__logo-link" href="/" title="Google"> <div class="glue-header__logo-container"> <svg role="img" aria-hidden="true" class="glue-header__logo-svg"> <use xlink:href="/assets/images/glue-icons.svg#google-color-logo"></use> </svg> </div> <p class="glue-header__logo--product">AIPs</p> </a> </div>  <a href="#page-content" class="glue-header__skip-content"> <p class="glue-header__skip-content-text">Jump to Content</p> </a> </div> </div>  <div class="glue-header__container"> <div class="glue-header__cta"> <a href="https://github.com/aip-dev/google.aip.dev" class="glue-button glue-button--high-emphasis"> <img src="/assets/images/github.png" class="github-logo"> View on GitHub </a> </div> </div> </div> </div> <div class="glue-header__drawer-backdrop"></div> </header> <div class="glue-page"> <main role="main" id="page-content"> <nav id="aip-nav" class="docs-component-nav"> <ul class="nav-list"> <li class="nav-item nav-item-header">AIPs by Scope</li> <li class="nav-item"> <a href="/general">General</a> </li> <li class="nav-item"> <a href="/cloud">Google Cloud Platform</a> </li> <li class="nav-item"> <a href="/auth">Auth</a> </li> <li class="nav-item"> <a href="/client-libraries">Client libraries</a> </li> <li class="nav-item"> <a href="/apps">GSuite</a> </li> <li class="nav-item"> <a href="/aog">Actions on Google</a> </li> <li class="nav-item nav-item-header">AIPs</li> <li class="nav-item"> <a href="/1"> <span class="aip-number">1</span> AIP Purpose and Guidelines </a> </li> <li class="nav-item"> <a href="/2"> <span class="aip-number">2</span> AIP Numbering </a> </li> <li class="nav-item"> <a href="/3"> <span class="aip-number">3</span> AIP Versioning </a> </li> <li class="nav-item"> <a href="/8"> <span class="aip-number">8</span> AIP Style and Guidance </a> </li> <li class="nav-item"> <a href="/9"> <span class="aip-number">9</span> Glossary </a> </li> <li class="nav-item"> <a href="/100"> <span class="aip-number">100</span> API Design Review FAQ </a> </li> <li class="nav-item"> <a href="/111"> <span class="aip-number">111</span> Planes </a> </li> <li class="nav-item"> <a href="/121"> <span class="aip-number">121</span> Resource-oriented design </a> </li> <li class="nav-item"> <a href="/122"> <span class="aip-number">122</span> Resource names </a> </li> <li class="nav-item"> <a href="/123"> <span class="aip-number">123</span> Resource types </a> </li> <li class="nav-item"> <a href="/124"> <span class="aip-number">124</span> Resource association </a> </li> <li class="nav-item"> <a href="/126"> <span class="aip-number">126</span> Enumerations </a> </li> <li class="nav-item"> <a href="/127"> <span class="aip-number">127</span> HTTP and gRPC Transcoding </a> </li> <li class="nav-item"> <a href="/128"> <span class="aip-number">128</span> Declarative-friendly interfaces </a> </li> <li class="nav-item"> <a href="/129"> <span class="aip-number">129</span> Server-Modified Values and Defaults </a> </li> <li class="nav-item"> <a href="/130"> <span class="aip-number">130</span> Methods </a> </li> <li class="nav-item"> <a href="/131"> <span class="aip-number">131</span> Standard methods: Get </a> </li> <li class="nav-item"> <a href="/132"> <span class="aip-number">132</span> Standard methods: List </a> </li> <li class="nav-item"> <a href="/133"> <span class="aip-number">133</span> Standard methods: Create </a> </li> <li class="nav-item"> <a href="/134"> <span class="aip-number">134</span> Standard methods: Update </a> </li> <li class="nav-item"> <a href="/135"> <span class="aip-number">135</span> Standard methods: Delete </a> </li> <li class="nav-item"> <a href="/136"> <span class="aip-number">136</span> Custom methods </a> </li> <li class="nav-item"> <a href="/140"> <span class="aip-number">140</span> Field names </a> </li> <li class="nav-item"> <a href="/141"> <span class="aip-number">141</span> Quantities </a> </li> <li class="nav-item"> <a href="/142"> <span class="aip-number">142</span> Time and duration </a> </li> <li class="nav-item"> <a href="/143"> <span class="aip-number">143</span> Standardized codes </a> </li> <li class="nav-item"> <a href="/144"> <span class="aip-number">144</span> Repeated fields </a> </li> <li class="nav-item"> <a href="/145"> <span class="aip-number">145</span> Ranges </a> </li> <li class="nav-item"> <a href="/146"> <span class="aip-number">146</span> Generic fields </a> </li> <li class="nav-item"> <a href="/147"> <span class="aip-number">147</span> Sensitive fields </a> </li> <li class="nav-item"> <a href="/148"> <span class="aip-number">148</span> Standard fields </a> </li> <li class="nav-item"> <a href="/149"> <span class="aip-number">149</span> Unset field values </a> </li> <li class="nav-item"> <a href="/151"> <span class="aip-number">151</span> Long-running operations </a> </li> <li class="nav-item"> <a href="/152"> <span class="aip-number">152</span> Jobs </a> </li> <li class="nav-item"> <a href="/153"> <span class="aip-number">153</span> Import and export </a> </li> <li class="nav-item"> <a href="/154"> <span class="aip-number">154</span> Resource freshness validation </a> </li> <li class="nav-item"> <a href="/155"> <span class="aip-number">155</span> Request identification </a> </li> <li class="nav-item"> <a href="/156"> <span class="aip-number">156</span> Singleton resources </a> </li> <li class="nav-item"> <a href="/157"> <span class="aip-number">157</span> Partial responses </a> </li> <li class="nav-item"> <a href="/158"> <span class="aip-number">158</span> Pagination </a> </li> <li class="nav-item"> <a href="/159"> <span class="aip-number">159</span> Reading across collections </a> </li> <li class="nav-item"> <a href="/160"> <span class="aip-number">160</span> Filtering </a> </li> <li class="nav-item"> <a href="/161"> <span class="aip-number">161</span> Field masks </a> </li> <li class="nav-item"> <a href="/162"> <span class="aip-number">162</span> Resource Revisions </a> </li> <li class="nav-item"> <a href="/163"> <span class="aip-number">163</span> Change validation </a> </li> <li class="nav-item"> <a href="/164"> <span class="aip-number">164</span> Soft delete </a> </li> <li class="nav-item"> <a href="/165"> <span class="aip-number">165</span> Criteria-based delete </a> </li> <li class="nav-item"> <a href="/180"> <span class="aip-number">180</span> Backwards compatibility </a> </li> <li class="nav-item"> <a href="/181"> <span class="aip-number">181</span> Stability levels </a> </li> <li class="nav-item"> <a href="/182"> <span class="aip-number">182</span> External software dependencies </a> </li> <li class="nav-item"> <a href="/185"> <span class="aip-number">185</span> API Versioning </a> </li> <li class="nav-item"> <a href="/191"> <span class="aip-number">191</span> File and directory structure </a> </li> <li class="nav-item"> <a href="/192"> <span class="aip-number">192</span> Documentation </a> </li> <li class="nav-item"> <a href="/193"> <span class="aip-number">193</span> Errors </a> </li> <li class="nav-item"> <a href="/194"> <span class="aip-number">194</span> Automatic retry configuration </a> </li> <li class="nav-item"> <a href="/200"> <span class="aip-number">200</span> Precedent </a> </li> <li class="nav-item"> <a href="/202"> <span class="aip-number">202</span> Fields </a> </li> <li class="nav-item"> <a href="/203"> <span class="aip-number">203</span> Field behavior documentation </a> </li> <li class="nav-item"> <a href="/205"> <span class="aip-number">205</span> Beta-blocking changes </a> </li> <li class="nav-item"> <a href="/210"> <span class="aip-number">210</span> Unicode </a> </li> <li class="nav-item"> <a href="/211"> <span class="aip-number">211</span> Authorization checks </a> </li> <li class="nav-item"> <a href="/213"> <span class="aip-number">213</span> Common components </a> </li> <li class="nav-item"> <a href="/214"> <span class="aip-number">214</span> Resource expiration </a> </li> <li class="nav-item"> <a href="/215"> <span class="aip-number">215</span> API-specific protos </a> </li> <li class="nav-item"> <a href="/216"> <span class="aip-number">216</span> States </a> </li> <li class="nav-item"> <a href="/217"> <span class="aip-number">217</span> Unreachable resources </a> </li> <li class="nav-item"> <a href="/231"> <span class="aip-number">231</span> Batch methods: Get </a> </li> <li class="nav-item"> <a href="/233"> <span class="aip-number">233</span> Batch methods: Create </a> </li> <li class="nav-item"> <a href="/234"> <span class="aip-number">234</span> Batch methods: Update </a> </li> <li class="nav-item"> <a href="/235"> <span class="aip-number">235</span> Batch methods: Delete </a> </li> <li class="nav-item"> <a href="/236"> <span class="aip-number">236</span> Policy preview </a> </li> </ul> </nav> <section id="jump-content"> <aside id="aip-sidebar" class="docs-component-sidebar"> <section id="aip-toc" class="docs-component-sidebar-toc"> <div class="toc"><span class="toctitle">Contents</span><ul> <li><a href="#why-protocol-buffers">Why Protocol Buffers?</a></li> <li><a href="#whats-all-this-googley-stuff">What's all this Googley stuff?</a></li> <li><a href="#i-like-most-of-these-aips-but-some-make-no-sense-for-me-what-do-i-do">I like most of these AIPs, but some make no sense for me. What do I do?</a></li> <li><a href="#why-arent-all-of-googles-products-listed-here">Why aren't all of Google's products listed here?</a></li> <li><a href="#i-have-a-question-that-isnt-answered-here-what-do-i-do">I have a question that isn't answered here. What do I do?</a></li> </ul> </div> </section> <section class="docs-component-sidebar-actions"> <ul> <li><a href="https://github.com/aip-dev/google.aip.dev/issues/">File Bug</a></li> <li><a href="https://github.com/aip-dev/google.aip.dev/blob/master/pages/general/faq.md">View source</a></li> <li><a href="https://github.com/aip-dev/google.aip.dev/edit/master/pages/general/faq.md">Edit this page</a></li> </ul> </section> </aside> <section id="aip-main" class="docs-component-main"> <section class="section-breadcrumbs"> <nav class="glue-breadcrumbs glue-mod-mt-std glue-mod-mb-std" aria-label="You are here." > <ol class="glue-breadcrumbs__list aip-breadcrumbs"> <li class="glue-breadcrumbs__item" aria-level="1"> <a class="glue-breadcrumbs__link" href="/"> API Improvement Proposals </a> </li> <li class="glue-breadcrumbs__item glue-breadcrumbs__item--active" aria-level="3"> Frequently asked questions </li> </ol> </nav> </section> <h1 id="frequently-asked-questions">Frequently asked questions</h1> <p><strong>Note:</strong> Have a question not answered here? <a href="https://github.com/aip-dev/google.aip.dev/issues/new?labels=question">Ask us on GitHub!</a></p> <h3 id="why-protocol-buffers">Why Protocol Buffers?</h3> <p>At Google, we define all of our APIs using Protocol Buffers (<code>.proto</code> files). While we realize there are lots of other, newer ways of defining these interfaces (e.g., OpenAPI, RAML, etc), we had to standardize on something and since we're Google, we use protos.</p> <p>This also leads to some very Google-specific ways of mapping proto RPCs to RESTful URIs (<code>google.api.http</code> annotations). If you're not using protos, feel free to follow the <em>spirit</em> of the API guidance since you won't be able to follow the example snippets exactly as provided.</p> <h3 id="whats-all-this-googley-stuff">What's all this Googley stuff?</h3> <p>Originally, our API guidance was written by and for Googlers only. We're in the process of making this guidance more general to the world, but that's far from complete. If you see things like "Submit a CL" or "Talk to your PA lead", feel free to send pull requests to fix these oversights.</p> <p>(CL stands for "Change List" which is sort of like a GitHub Pull Request, and PA stands for "Product Area" meaning things like "Google Maps" or "Google Workspace".)</p> <h3 id="i-like-most-of-these-aips-but-some-make-no-sense-for-me-what-do-i-do">I like most of these AIPs, but some make no sense for me. What do I do?</h3> <p>Sometimes guidance from AIPs makes lots of sense for Google (perhaps due to its size or scale) but no sense at all for others. This is much more common than we originally thought, so we added a way for sub-teams to override guidance that doesn't make sense for those teams.</p> <p>If you want to adopt most of the AIPs but have a few that make no sense for your team, you can override those few and stick to just the ones that make sense for you.</p> <h3 id="why-arent-all-of-googles-products-listed-here">Why aren't all of Google's products listed here?</h3> <p>When this project was first published, the AIP program was still relatively new. Even with time, not all of Google has adopted AIPs as the way of documenting their API guidance and policies. We're working on broadening the scope to more and more areas, both inside and outside Google, so this will continue to evolve.</p> <p>If you work at Google and want your team to adopt AIPs for documenting how your team does APIs, feel free to reach out to get in touch with us!</p> <h3 id="i-have-a-question-that-isnt-answered-here-what-do-i-do">I have a question that isn't answered here. What do I do?</h3> <p>We're still pretty new and haven't built up a long list of frequently asked questions, so if you have a question not answered here, you can always <a href="https://github.com/aip-dev/google.aip.dev/issues/new?labels=question">ask us on GitHub</a> by filing an issue.</p> <p>And if you already know the answer to a question that would be helpful for others, <a href="https://github.com/aip-dev/google.aip.dev/edit/master/pages/general/faq.md">send us a pull request adding it to this page</a>!</p> <footer> Except as otherwise noted, the content of this page is licensed under the <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 License</a>, and code samples are licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>. <span class="no-print">For details, see <a href="/licensing">content licensing</a>.</span> </footer> </section> </section> </main> </div> <script src="//www.gstatic.com/external_hosted/hammerjs/v2_0_2/hammer.min.js"></script> <script src="//www.gstatic.com/glue/v22_1/glue-vanilla.min.js"></script> <script type="text/javascript"> const headerElement = document.querySelector('.glue-header'); if (headerElement) { new window.glue.ui.header.Header(headerElement); } </script> </body> </html>

CINXE.COM

Frequently asked questions