### Start Policy Experiment Preview Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0236.md Starts previewing a PolicyExperiment. This triggers the system to start generating logs to evaluate the PolicyExperiment. The operation returns a google.longrunning.Operation. ```APIDOC ## POST /v1/{name=policies/*/experiments/*}:startPreview ### Description Starts previewing a PolicyExperiment. This triggers the system to start generating logs to evaluate the PolicyExperiment. ### Method POST ### Endpoint /v1/{name=policies/*/experiments/*}:startPreview ### Parameters #### Path Parameters - **name** (string) - Required - The name of the PolicyExperiment. ### Request Example { "example": "" } ### Response #### Success Response (200) - **response** (PolicyExperiment) - The result of the long-running operation. - **metadata** (StartPreviewPolicyExperimentMetadata) - Metadata for the long-running operation. ``` -------------------------------- ### Interface Name Example in .proto file Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0190.md The 'Library' is an example of an interface name used in a .proto file, distinct from service names like 'pubsub.googleapis.com'. ```proto service Library { rpc ListBooks(...) returns (...); rpc ... } ``` -------------------------------- ### Example X.509 Certificate and Private Key Output Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4114.md This is an example of the output format for a fetched client certificate and its corresponding private key, printed to stdout by a cert provider command. It includes the certificate details and the private key. ```text -----BEGIN CERTIFICATE----- Common Name: Google Endpoint Verification Valid From: November 10, 2019 Valid To: November 10, 2020 Serial Number: 4921083229008411918 (0x444b331faf2dbd0e) ... -----END CERTIFICATE----- -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- ``` -------------------------------- ### Full Resource Name Examples Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0122.md Shows examples of full resource names, which are schemeless URIs used to refer to resources in arbitrary APIs. This format includes the owning API's service name. ```uri //library.googleapis.com/publishers/123/books/les-miserables ``` ```uri //calendar.googleapis.com/users/vhugo1802 ``` -------------------------------- ### Example BII Arguments: grant and date Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/aog/3022.md Demonstrates hypothetical BII arguments 'grant' and 'date' with their Schema.org types. This example illustrates how to reference nested properties using dot notation for API mapping. ```json { "grant": { "@context": "http://schema.org", "@type": "MonetaryGrant", "funder": { "@type": "Organization", "name": "Google" }, "amount": { "@type": "MonetaryAmount", "currency": "USD", "value": 100 } }, "date": "2000-01-01" } ``` -------------------------------- ### Example Resource Names Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0122.md Illustrates common formats for resource names, including nested resources and simple user references. ```text publishers/123/books/les-miserables users/vhugo1802 ``` -------------------------------- ### Generated Go client documentation for a versioned API Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4236.md Example of generated Go client documentation reflecting the API version specified in the proto definition. ```go // The LibraryClient is a client for interacting with the Cloud Library... // // This client uses LibraryService version 2026-01-01. type LibraryClient struct {} ``` -------------------------------- ### Example BII Argument with Multiple Values Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/aog/3022.md Illustrates a BII argument 'menuItem' with a property 'menuAddOn' that has multiple values. This example shows how to reference specific values within an array using bracketed indices. ```json { "menuItem": { "@context": "http://schema.org", "@type": "MenuItem", "name": "pizza", "menuAddOn": { "@type": "MenuItem", "name": "pineapple" }, "menuAddOn": { "@type": "MenuItem", "name": "extra cheese" } }, "date": "2000-01-01" } ``` -------------------------------- ### Audio Segment Example Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0142.md Demonstrates using google.protobuf.Duration for relative time segments within a stream. ```proto message AudioSegment { // The duration relative to the start of the stream representing the // beginning of the segment. google.protobuf.Duration start_offset = 1; // The total length of the segment. google.protobuf.Duration segment_duration = 2; } ``` -------------------------------- ### Proto definition with API version Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4236.md Example of an API interface definition with the `google.api.api_version` annotation. ```proto service LibraryService { option (google.api.api_version) = "2026-01-01"; } ``` -------------------------------- ### Resource Naming with User-Specified and System-Generated IDs Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0133.md Illustrates resource naming conventions for books, showing examples of both user-specified IDs and system-generated IDs. ```plaintext publishers/lacroix/books/les-miserables publishers/012345678-abcd-cdef/books/12341234-5678-abcd ``` -------------------------------- ### Protoc Invocation with Plugin Options Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4290.md Example of a protoc command that includes plugin options for language-specific generators. Use this when configuring micro-generators via protoc. ```bash protoc --proto_path {path/to/common/protos} --proto_path /in/ \ --{LANG}_gapic_out /out/ \ --{LANG}_gapic_opt "go-gapic-package=GO_PACKAGE_VALUE" \ `find /in/ -name *.proto` ``` -------------------------------- ### Flight Record Example Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0142.md Illustrates the distinction between timestamps and durations for representing flight events. ```proto message FlightRecord { // The absolute point in time when the plane took off. google.protobuf.Timestamp takeoff_time = 1; // The length (duration) of the flight, from takeoff to landing. google.protobuf.Duration flight_duration = 2; } ``` -------------------------------- ### Proto3 Message with Field Naming Examples Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0140.md Demonstrates the use of 'string' for image URLs and 'uri' for general URIs within a proto3 message definition. ```proto message Book { string name = 1 [(google.api.field_behavior) = IDENTIFIER]; // A URL pointing to an image of the book. string image_url = 2; // A URI identifying the book. // This could be an ISBN or a URL. string uri = 3; } ``` -------------------------------- ### Format an image as GIF with specific options Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/cloud/2602.md Example of a command to format an image as GIF, including format-specific options like loop behavior and frame delay. ```bash gcloud images format gif --source-file=foo --destination-file=bar \ --loop-forever --frame-delay=1ms ``` -------------------------------- ### Proto definitions with multiple API versions Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4236.md Example of multiple API interface definitions with distinct `google.api.api_version` annotations. ```proto service LibraryService { option (google.api.api_version) = "2026-01-01"; } service BookService { option (google.api.api_version) = "2026-05-15"; } service ShelfService { option (google.api.api_version) = "2026-02-05"; } ``` -------------------------------- ### Sample Executable Error Response Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4117.md An example of an error response from an executable source, indicating authorization failure. ```json { "version": 1, "success": false, "code": "401", "message": "Caller not authorized." } ``` -------------------------------- ### API response example with concurrency limit Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/cloud/2604.md Illustrates an API response showing a concurrency limit and its type, highlighting potential user confusion. ```yaml concurrencyControl: concurrencyLimit: 10 limitType: PERCENT ``` -------------------------------- ### Format an image as JPEG with specific options Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/cloud/2602.md Example of a command to format an image as JPEG, including format-specific options like DCT method and smoothing. ```bash gcloud images format jpeg --source-file=foo --destination-file=bar \ --dct-method=integer --smoothing=0.1 --subsampling=4:4:4 ``` -------------------------------- ### External Account Configuration File Example Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4117.md This JSON structure defines an external account configuration, specifying details for token exchange using file-sourced credentials. ```json { "type": "external_account", "audience": "//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID", "subject_token_type": "urn:ietf:params:oauth:token-type:saml2", "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$EMAIL:generateAccessToken", "token_url": "https://sts.googleapis.com/v1/token", "credential_source": { "file": "/var/run/saml/assertion/token" } } ``` -------------------------------- ### Batch Create Books (Asynchronous) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0233.md Example of a batch create RPC that returns a long-running operation. This allows for asynchronous processing of batch book creation. ```APIDOC ## BatchCreateBooks (Asynchronous) ### Description Allows users to create multiple books asynchronously by returning a long-running operation. ### Method POST ### Endpoint /v1/{parent=publishers/*}/books:batchCreate ### Parameters #### Request Body - **requests** (array) - Required - An array of `CreateBookRequest` messages specifying the books to create. - **parent** (string) - Optional - The parent resource shared by all books being created. Format: publishers/{publisher}. If set, the parent field in the child requests must match or be empty. ### Request Example ```json { "requests": [ { "book": { "title": "Book 1", "author": "Author 1" } }, { "book": { "title": "Book 2", "author": "Author 2" } } ], "parent": "publishers/123" } ``` ### Response #### Success Response (200) - **operation** (object) - A long-running operation object. - **name** (string) - The name of the operation. - **metadata** (object) - Operation metadata, e.g., `BatchCreateBooksOperationMetadata`. - **response** (object) - The eventual response of the operation, e.g., `BatchCreateBooksResponse`. #### Response Example ```json { "name": "operations/12345", "metadata": { "@type": "type.googleapis.com/google.aip.dev.BatchCreateBooksOperationMetadata", "create_time": "2023-10-27T10:00:00Z" }, "response": { "@type": "type.googleapis.com/google.aip.dev.BatchCreateBooksResponse", "books": [ { "name": "publishers/123/books/abc", "title": "Book 1", "author": "Author 1" }, { "name": "publishers/123/books/def", "title": "Book 2", "author": "Author 2" } ], "total_size": 2 } } ``` ``` -------------------------------- ### Proto RPC Definition with HTTP POST Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4222.md An example of an RPC definition using `google.api.http` with a POST method, defining a URI template with a parent variable. ```proto rpc CreateTopic(CreateTopicRequest) { option (google.api.http).post = "{parent=projects/*}/topics"; } ``` -------------------------------- ### Request with Explicit Visibility Label Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0185.md This example demonstrates how a client can specify an explicit visibility label in an HTTP GET request header. This allows the client to request access to API features tagged with a specific label. ```http GET /v1/projects/my-project/topics HTTP/1.1 Host: pubsub.googleapis.com Authorization: Bearer y29.... X-Goog-Visibilities: PREVIEW ``` -------------------------------- ### Batch Get Response Message Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0231.md Defines the response structure for a batch get operation. The repeated field should contain the retrieved resources in the same order as the request. ```proto message BatchGetBooksResponse { // Books requested. repeated Book books = 1; } ``` -------------------------------- ### Start Policy Experiment Preview RPC Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0236.md Initiates the preview of a Policy Experiment, triggering log generation for evaluation. This method is required and must adhere to long-running operation guidelines. ```proto rpc StartPreviewPolicyExperiment(StartPreviewPolicyExperimentRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{name=policies/*/experiments/*}:startPreview" body: "*" }; option (google.longrunning.operation_info) = { response_type: "PolicyExperiment" metadata_type: "StartPreviewPolicyExperimentMetadata" }; } // The request message for the startPreview custom method. message StartPreviewPolicyExperimentRequest { // The name of the PolicyExperiment. string name = 1; } ``` -------------------------------- ### Get Request Message Structure Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0131.md Defines the request message for a Get RPC, containing the resource name. The `name` field is required and references the resource type. ```proto message GetBookRequest { // The name of the book to retrieve. // Format: publishers/{publisher}/books/{book} string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "library.googleapis.com/Book" }]; } ``` -------------------------------- ### Batch Get RPC Definition Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0231.md Defines the RPC signature for a batch get operation, including the HTTP mapping. Use this pattern for retrieving multiple resources atomically. ```proto rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) { option (google.api.http) = { get: "/v1/{parent=publishers/*}/books:batchGet" }; } ``` -------------------------------- ### Resource-Based Custom Method Example (Proto) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0136.md Defines a custom RPC method for archiving a book, including its HTTP mapping. This pattern is suitable for operations on a specific resource. ```proto rpc ArchiveBook(ArchiveBookRequest) returns (ArchiveBookResponse) { option (google.api.http) = { post: "/v1/{name=publishers/*/books/*}:archive" body: "*" }; } ``` -------------------------------- ### JWT Header Example (Audience) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4111.md Example JWT header when using the 'audience' claim. Ensure the 'kid' field matches the service account's private key ID. ```json { "alg": "RS256", "typ": "JWT", "kid": "abcdef1234567890" } ``` -------------------------------- ### Batch Get Request Message Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0231.md Specifies the structure for a batch get request, including parent and resource names. Ensure the 'names' field documents the maximum number of resources allowed. ```proto message BatchGetBooksRequest { // The parent resource shared by all books being retrieved. // Format: publishers/{publisher} // If this is set, the parent of all of the books specified in `names` // must match this field. string parent = 1 [ (google.api.resource_reference) = { child_type: "library.googleapis.com/Book" }]; // The names of the books to retrieve. // A maximum of 1000 books can be retrieved in a batch. // Format: publishers/{publisher}/books/{book} repeated string names = 2 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "library.googleapis.com/Book" }]; } ``` -------------------------------- ### Generated client package documentation for multiple API versions Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4236.md Example of generated client package documentation listing client-interface-version tuples for different API versions. ```md ## API Versions * LibraryClient uses LibraryService version 2026-01-01 * BookClient uses BookService version 2026-05-15 * ShelfClient uses ShelfService version 2026-02-05 ``` -------------------------------- ### Get RPC Method Signature Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0131.md Defines the RPC for retrieving a book, including its HTTP mapping. The `name` field in the HTTP GET path is mapped to the `name` field in the request message. ```proto rpc GetBook(GetBookRequest) returns (Book) { option (google.api.http) = { get: "/v1/{name=publishers/*/books/*}" }; option (google.api.method_signature) = "name"; } ``` -------------------------------- ### Docker Image Invocation for Protoc Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/client-libraries/4290.md Example of how to run a Docker image for a gapic generator, passing plugin options. This demonstrates mounting volumes and specifying generator options. ```bash $ docker run --rm --user $UID \ --mount type=bind,source=`pwd`/a/b/c/v1/,destination=/in/a/b/c/v1/,readonly \ --mount type=bind,source=/path/to/dest/,destination=/out/ \ gcr.io/gapic-images/{GENERATOR} \ --go-gapic-package GO_PACKAGE_VALUE ``` -------------------------------- ### Proto Definition and RPC for Listing Singleton Resources Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0156.md Demonstrates how to define a ListConfigs RPC for a singleton resource, allowing it to be accessed as part of a parent's collection. The parent field in the request specifies the parent resource. ```proto rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) { option (google.api.http) = { get: "/v1/{parent=users/*}/configs" }; } ``` ```proto message ListConfigsRequest { // To list all configs, use `-` as the user id. // Formats: // * `users/-` // * `users/{user}` // // Note: Specifying an actual user id will return a collection of one config. // Use GetConfig instead. string parent = 1 [ (google.api.resource_reference).child_type = "api.googleapis.com/Config"]; // other standard pagination fields... } ``` -------------------------------- ### Collection-Based Custom Method Example (Proto) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0136.md Illustrates a custom RPC method for sorting books within a publisher's collection. This is used when the operation applies to a collection of resources. ```proto rpc SortBooks(SortBooksRequest) returns (SortBooksResponse) { option (google.api.http) = { post: "/v1/{parent=publishers/*}/books:sort" body: "*" }; } ``` -------------------------------- ### Get Unique Resource Across Collections Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0159.md Use the wildcard '-' in a Get method to retrieve a unique resource without knowing its parent collection. The resource ID must be unique across parent collections. ```http GET https://example.googleapis.com/v1/publishers/-/books/{book} ``` -------------------------------- ### Format an image as PNG with specific options Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/cloud/2602.md Example of a command to format an image as PNG, including format-specific options like color type and bits per channel. ```bash gcloud images format png --source-file=foo --destination-file=bar \ --color-type=0 --bits-per-channel=16 ``` -------------------------------- ### Batch Get Request Message Structure Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0231.md Defines the structure for a batch Get request, including a parent field and a repeated field for individual resource requests. This pattern is useful when retrieving multiple resources that share a common parent. ```proto message BatchGetBooksRequest { // The parent resource shared by all books being retrieved. // Format: publishers/{publisher} // If this is set, the parent field in the GetBookRequest messages // must either be empty or match this field. string parent = 1 [ (google.api.resource_reference) = { child_type: "library.googleapis.com/Book" }]; // The requests specifying the books to retrieve. // A maximum of 1000 books can be retrieved in a batch. repeated GetBookRequest requests = 2 [(google.api.field_behavior) = REQUIRED]; } ``` -------------------------------- ### JWT Payload Example (Audience) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4111.md Example JWT payload when using the 'audience' claim. The 'iss' and 'sub' fields should be the service account's email, 'aud' the target API, and 'iat'/'exp' define the token's validity period (3600 seconds). ```json { "iss": "123456-compute@developer.gserviceaccount.com", "sub": "123456-compute@developer.gserviceaccount.com", "aud": "https://pubsub.googleapis.com/", "iat": 1511900000, "exp": 1511903600 } ``` -------------------------------- ### Stateless Custom Method Example (Proto) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0136.md Shows a stateless custom RPC method for translating text, associated with a project scope. This pattern is for operations that do not directly modify persistent data. ```proto rpc TranslateText(TranslateTextRequest) returns (TranslateTextResponse) { option (google.api.http) = { post: "/v1/{project=projects/*}:translateText" body: "*" }; } ``` -------------------------------- ### JWT Payload Example (Scope) Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/auth/4111.md Example JWT payload when using the 'scope' claim. 'iss' and 'sub' are the service account's email, 'scope' defines the permissions, and 'iat'/'exp' set the token's validity (3600 seconds). Note that 'aud' and 'scope' cannot be used together. ```json { "iss": "123456-compute@developer.gserviceaccount.com", "sub": "123456-compute@developer.gserviceaccount.com", "scope": "https://www.googleapis.com/auth/cloud-platform", "iat": 1511900000, "exp": 1511903600 } ``` -------------------------------- ### Configure URL and Base URL in _config.yaml Source: https://github.com/aip-dev/google.aip.dev/blob/master/pages/general/adopting.md If not creating a new domain, add the 'baseurl' property to '_config.yaml' to include any additional path information appended to the domain. ```yaml url: https://jdoe123.github.io baseurl: /my-aips ``` -------------------------------- ### gcloud list command with flag argument Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/cloud/2603.md Illustrates the recommended gcloud command format for listing resources using a flag for the parent collection. ```bash gcloud publishers books list --publisher=PUBLISHER ``` -------------------------------- ### Example AIP Shell Structure Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0008.md This markdown snippet demonstrates the recommended structure for an AIP document, including headings for title, introduction, guidance, rationale, history, further reading, and changelog. ```markdown # AIP title The introductory text explains the background and reason why the AIP exists. It lays out the basic question, but does not tell the reader what to do. ## Guidance The "guidance" section helps the reader know what to do. A common format for the guidance section is a high-level imperative, followed by an example, followed by a bulleted list explaining the example. ### Subsection Individual subsections can be cited individually, and further elaborate details. ## Rationale The "rationale" section is optional, and helps the reader understand the motivation behind specific guidance within the AIP. Deeper explanations of design justification and tradeoffs **must** be in the rationale instead of other sections, to ensure the rest of the document acts as an easily actionable reference. ## History The "history" section is optional, and documents events and context around a significant edit to an AIP. For example, explanation of rewrite would be included in this section While the changelog is a dotted list of one-line summaries of changes to an AIP, the history section should elaborate on significant events in a descriptive format. The section **must not** be used to exhaustively enumerate all changes. This is what the changelog provides. ## Further reading A bulleted list of (usually) other AIPs, in the following format: - [AIP-1](./0001.md): AIP purpose and guidelines ## Changelog A bulleted list of changes in reverse chronological order, using the following format: - **2020-02-18**: Specified ordering. - **2019-07-01**: Added a subsection clarifying XYZ. ``` -------------------------------- ### API Improvement Proposal Stakeholder Flowchart Source: https://github.com/aip-dev/google.aip.dev/blob/master/aip/general/0001.md Visualizes the escalation path for API Improvement Proposals, starting from the API Producer. ```graphviz digraph d_front_back { rankdir=BT; ranksep=0.3; node [ style="filled,solid" shape=box fontname="Roboto" ]; producer [ label="API Producer" ]; editors [ label="AIP Editors" ]; tl_infra [ label="Infrastructure TL" ]; tl_design [ label="Design TL" ]; tl [ label="TL" ]; producer -> editors; editors -> tl_infra -> tl; editors -> tl_design -> tl; } ```