### Cursor-Based Pagination Example - Initial Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of an initial GET request for listing books with a specified page size.

```http
GET /v1/publishers/acme-books/books?pageSize=10
```

--------------------------------

### Example ListBooks Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example HTTP GET request for listing books, including Host and Authorization headers.

```http
GET /v1/publishers/acme-books/books?pageSize=2 HTTP/1.1
Host: library.example.com
Authorization: Bearer token
```

--------------------------------

### WriteBook Initial Request Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of an initial POST request to initiate the WriteBook operation.

```http
POST /v1/publishers/acme-books/books:write HTTP/1.1

{
  "title": "New Book"
}
```

--------------------------------

### Cursor-Based Pagination Example - Subsequent Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of a subsequent GET request for listing books, using the nextPageToken from the previous response.

```http
GET /v1/publishers/acme-books/books?pageSize=10&pageToken=page2_token_abc123
```

--------------------------------

### Example GetBook Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Illustrates an HTTP GET request to retrieve a specific book, including host and authorization headers.

```http
GET /v1/publishers/acme-books/books/learning-go HTTP/1.1
Host: library.example.com
Authorization: Bearer token
```

--------------------------------

### Write Book Operation Metadata Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

An example metadata message for a WriteBook operation. It includes fields for start time, progress percentage, and the current state of the operation.

```proto
message WriteBookMetadata {
  google.protobuf.Timestamp start_time = 1;
  int32 progress_percent = 2;
  
  enum State {
    STATE_UNSPECIFIED = 0;
    RUNNING = 1;
    CANCELLING = 2;
    CANCELLED = 3;
    FAILED = 4;
  }
  
  State state = 3;
}
```

--------------------------------

### Get a Resource

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

Demonstrates how to retrieve a single resource using a GET request.

```HTTP
GET /v1/publishers/acme/books/learning-go
→ {name: "...", title: "Learning Go", authors: [...], rating: 4.5}
```

--------------------------------

### Example Book Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Shows an example JSON response after successfully adding an author to a book, including updated book details.

```json
{
  "name": "publishers/acme-books/books/learning-go",
  "isbn": "978-1491990537",
  "title": "Learning Go",
  "authors": ["John Doe", "Jane Smith"],
  "rating": 4.5
}
```

--------------------------------

### Publisher Resource Name Examples

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Provides concrete examples of publisher resource names.

```text
publishers/acme-books
```

```text
publishers/penguin-group
```

```text
publishers/oreilly
```

--------------------------------

### WriteBook Immediate Response Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of the immediate response after initiating a WriteBook operation, indicating an ongoing LRO.

```json
{
  "name": "operations/123456/locations/global/operations/write_book_abc",
  "metadata": {
    "@type": "type.googleapis.com/WriteBookMetadata",
    "startTime": "2024-01-15T10:30:00Z",
    "progressPercent": 0,
    "state": "RUNNING"
  },
  "done": false
}
```

--------------------------------

### Book Resource Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

An example resource representing a book, including its name, ISBN, title, authors, rating, and format.

```proto
message Book {
  string name = 1;              // "publishers/{pub}/books/{book}"
  string isbn = 2;
  string title = 3;
  repeated string authors = 4;
  float rating = 5;
  Format format = 6;            // HARDBACK, PAPERBACK, EBOOK, AUDIOBOOK
}
```

--------------------------------

### WriteBook Poll Operation Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of a GET request to poll the status of an ongoing WriteBook operation.

```http
GET /v1/operations/123456/locations/global/operations/write_book_abc
```

--------------------------------

### Standard Resource 'name' Field Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Demonstrates the 'name' field within a protobuf message, which must be populated with the resource's defined pattern. The example shows a 'Book' resource name.

```protobuf
message Book {
  string name = 1;  // "publishers/acme-books/books/learning-go"
}
```

--------------------------------

### Example ListBooks Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example JSON response for the ListBooks request, containing a list of books and a nextPageToken.

```json
{
  "results": [
    {
      "name": "publishers/acme-books/books/learning-go",
      "isbn": "978-1491990537",
      "title": "Learning Go",
      "authors": ["John Doe"],
      "rating": 4.5
    },
    {
      "name": "publishers/acme-books/books/programming-rust",
      "isbn": "978-1491927281",
      "title": "Programming Rust",
      "authors": ["Jim Blandy", "Jason Orendorff"],
      "rating": 4.7
    }
  ],
  "nextPageToken": "CAEQ2gIIAhoCCgA="
}
```

--------------------------------

### Example ArchiveBook Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Shows an example JSON response after successfully archiving a book, including the URI where the archived book can be found.

```json
{
  "uri": "gs://archive-bucket/publishers/acme-books/books/learning-go.pdf"
}
```

--------------------------------

### WriteBook Completion Response Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of the final response when a WriteBook operation has completed successfully.

```json
{
  "name": "operations/123456/locations/global/operations/write_book_abc",
  "metadata": {
    "@type": "type.googleapis.com/WriteBookMetadata",
    "startTime": "2024-01-15T10:30:00Z",
    "progressPercent": 100,
    "state": "RUNNING"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/WriteBookResponse",
    "text": "Book content..."
  }
}
```

--------------------------------

### Example SortBooks Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example empty JSON response for a successful SortBooks request.

```json
{}
```

--------------------------------

### Go Client Example with Method Signature

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Demonstrates a simplified Go client method call generated using the google.api.method_signature option.

```go
// Go example
book, err := client.GetBook(ctx, "publishers/acme/books/123")
```

--------------------------------

### Go Client Example without Method Signature

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Illustrates a more verbose Go client method call when google.api.method_signature is not used.

```go
// Without method signature
req := &GetBookRequest{Name: "publishers/acme/books/123"}
book, err := client.GetBook(ctx, req)
```

--------------------------------

### Example SortBooks Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example HTTP POST request to the SortBooks endpoint, specifying the publisher and the field for sorting.

```http
POST /v1/publishers/acme-books/books:sort HTTP/1.1
Host: library.example.com
Authorization: Bearer token
Content-Type: application/json

{
  "field": "rating"
}
```

--------------------------------

### Example UndeleteBook Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Shows an example HTTP POST request to undelete a specific book resource.

```http
POST /v1/publishers/acme-books/books/learning-go:undelete HTTP/1.1
Host: library.example.com
Authorization: Bearer token
Content-Type: application/json

{}
```

--------------------------------

### Example ArchiveBook Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Illustrates an example HTTP POST request to archive a book, specifying the book name and desired MIME type.

```http
POST /v1/publishers/acme-books/books/learning-go:archive HTTP/1.1
Host: library.example.com
Authorization: Bearer token
Content-Type: application/json

{
  "mime_type": "application/pdf"
}
```

--------------------------------

### List Resources with Pagination

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

Shows how to list resources with pagination using pageSize and pageToken parameters. The second example demonstrates fetching the last page.

```HTTP
GET /v1/publishers/acme/books?pageSize=10
→ {results: [...], nextPageToken: "token"}
```

```HTTP
GET /v1/publishers/acme/books?pageSize=10&pageToken=token
→ {results: [...], nextPageToken: ""}  // last page
```

--------------------------------

### Standard Get and List Method Flow

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/README.md

Describes the typical client-server interaction for Get and List operations, including pagination for List methods.

```text
1. Client calls GetBook("publishers/acme-books/books/learning-go")
2. Server retrieves resource and returns Book message
3. Client uses resource data

1. Client calls ListBooks("publishers/acme-books", pageSize=10)
2. Server returns ListBooksResponse with results[] and nextPageToken
3. If more pages exist, client calls ListBooks again with pageToken
```

--------------------------------

### HTTP Binding for GET Methods

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Configures an RPC method to use the HTTP GET verb, mapping it to a resource path with path binding.

```proto
option (google.api.http) = {
  get: "/v1/{name=publishers/*/books/*}"
};
```

--------------------------------

### Book Resource Name Examples

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Provides concrete examples of book resource names within a publisher's collection.

```text
publishers/acme-books/books/1234
```

```text
publishers/penguin-group/books/the-hobbit-v1
```

```text
publishers/oreilly/books/learning-go
```

--------------------------------

### Publisher Resource Naming Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Illustrates the naming pattern for a Publisher resource.

```plaintext
publishers/acme-books
```

--------------------------------

### Example GetBook Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Shows a JSON response for a successful GetBook request, detailing the book's properties.

```json
{
  "name": "publishers/acme-books/books/learning-go",
  "isbn": "978-1491990537",
  "title": "Learning Go",
  "authors": ["John Doe"],
  "rating": 4.5
}
```

--------------------------------

### Get Method Proto Definition

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Defines the protobuf structure for a Get method, including the HTTP GET mapping.

```proto
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=publishers/*/books/*}"
  };
}
```

--------------------------------

### Resource Path Format Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Shows the structure for a full resource name, combining service name, version, parent collection, and child identifiers. Also provides an equivalent representation in HTTP URL terms.

```text
service_name/version/parent_collection/{parent_id}/child_collection/{child_id}
```

```text
https://api.example.com/v1/publishers/acme-books/books/learning-go
```

--------------------------------

### Example AddAuthor HTTP Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Illustrates an example HTTP POST request to the AddAuthor endpoint, including necessary headers and the JSON request body.

```http
POST /v1/publishers/acme-books/books/learning-go:addAuthor HTTP/1.1
Host: library.example.com
Authorization: Bearer token
Content-Type: application/json

{
  "author": "Jane Smith"
}
```

--------------------------------

### Resource Naming Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/README.md

Illustrates a hierarchical resource name structure common in AIPs, showing collections and resource IDs.

```text
publishers/acme-books/books/learning-go
├─ Collection: publishers
├─ Resource ID: acme-books
├─ Sub-collection: books
└─ Resource ID: learning-go
```

--------------------------------

### Book Resource Naming Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Illustrates the naming pattern for a Book resource, including its parent publisher.

```plaintext
publishers/acme-books/books/123
```

--------------------------------

### Example TranslateText Request

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example HTTP POST request to the translateText endpoint, specifying content and target language.

```http
POST /v1/projects/my-project:translateText HTTP/1.1
Host: translation.example.com
Authorization: Bearer token
Content-Type: application/json

{
  "contents": [
    "Hello world",
    "Good morning"
  ],
  "targetLanguageCode": "es"
}
```

--------------------------------

### Get Method Proto Signature

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Defines the RPC signature for a Get method, including HTTP mapping and method signature.

```proto
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.http) = {
    get: "/v1/{name=publishers/*/books/*}"
  };
  option (google.api.method_signature) = "name";
}
```

--------------------------------

### Valid Money Example (EUR with Precision)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Demonstrates a valid JSON object for representing monetary values in EUR, showcasing the use of a higher exponent for precise decimal places. This example uses EUR.

```json
{
  "currency_code": "EUR",
  "quantity": {
    "significand": 123456789,
    "exponent": -4
  }
}
```

--------------------------------

### Valid Money Instance: USD

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Example of a valid monetary instance for US Dollars.

```json
{
  "currency_code": "USD",
  "quantity": {
    "significand": 5,
    "exponent": 0
  }
}
```

--------------------------------

### Valid Money Example (Cryptocurrency)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Shows a valid JSON object for representing cryptocurrency values, using a custom currency code (X-ETH) and an exponent of 0 for whole numbers. This example represents Ethereum.

```json
{
  "currency_code": "X-ETH",
  "quantity": {
    "significand": 25,
    "exponent": 0
  }
}
```

--------------------------------

### WriteBook Status Response (In Progress)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Example of a status response for an in-progress WriteBook operation.

```json
{
  "name": "operations/123456/locations/global/operations/write_book_abc",
  "metadata": {
    "@type": "type.googleapis.com/WriteBookMetadata",
    "startTime": "2024-01-15T10:30:00Z",
    "progressPercent": 50,
    "state": "RUNNING"
  },
  "done": false
}
```

--------------------------------

### Three-Tier Resource Pattern Example (Project)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Illustrates a common three-tier resource hierarchy pattern using a project as the top-level resource. This pattern is frequently used in Google Cloud APIs for multi-tenant services.

```text
projects/my-project-123
projects/acme-translation-service
```

--------------------------------

### Custom Method Flow Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/README.md

Outlines the interaction pattern for custom API methods, where a client initiates an operation and receives a custom response.

```text
1. Client calls ArchiveBook(name, mimeType)
2. Server performs custom operation (archive)
3. Server returns custom response (ArchiveBookResponse)
```

--------------------------------

### HTTP Method Patterns

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Examples of common HTTP methods used with resource patterns in API routing.

```http
GET /v1/{name=publishers/*/books/*}           # Get single book
```

```http
GET /v1/{parent=publishers/*}/books            # List books
```

```http
POST /v1/{publisher=publishers/*}/books:sort   # Custom method
```

--------------------------------

### Decimal Examples

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/types.md

Illustrates how to represent various decimal numbers using the Decimal type's significand and exponent fields. Useful for understanding value encoding.

```json
{significand: 17, exponent: 0}
```

```json
{significand: -5, exponent: -3}
```

```json
{significand: 335, exponent: 5}
```

```json
{significand: 1375, exponent: -3}
```

--------------------------------

### Valid Money Instance: EUR

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Example of a valid monetary instance for Euros.

```json
{
  "currency_code": "EUR",
  "quantity": {
    "significand": 1550,
    "exponent": -2
  }
}
```

--------------------------------

### Valid Money Example (USD)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Illustrates a valid JSON object for representing monetary values, including currency code and a nested quantity object. This example uses USD.

```json
{
  "currency_code": "USD",
  "quantity": {
    "significand": 9999,
    "exponent": -2
  }
}
```

--------------------------------

### HTTP Routing Patterns

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Patterns use wildcards for matching in HTTP routing. These examples show different levels of hierarchy matching.

```text
publishers/*/books/*
```

```text
publishers/*
```

```text
**
```

--------------------------------

### Get Method

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Retrieves a single resource by its name. This is a read-only operation and is fully idempotent.

```APIDOC
## GET /v1/{name=pattern}

### Description
Retrieves a single resource by its name. This operation is read-only and fully idempotent.

### Method
GET

### Endpoint
/v1/{name=pattern}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the resource to retrieve, following a specific pattern.

### Response
#### Success Response (200)
- **Book** (object) - The resource itself if found.

#### Response Example
{
  "example": "{\"name\": \"publishers/publisher1/books/book1\", \"title\": \"Example Book\"}"
}

### Status Codes
- 200 OK: Resource found
- 404 Not Found: Resource does not exist
```

--------------------------------

### Example: 0.01 EUR

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/types.md

Represents 0.01 EUR using the Money type, demonstrating a Decimal quantity with a negative exponent.

```json
{currency_code: "EUR", quantity: {significand: 1, exponent: -2}}
```

--------------------------------

### Valid Money Instance: Bitcoin (X-BTC)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Example of a valid monetary instance for Bitcoin, using a custom currency code.

```json
{
  "currency_code": "X-BTC",
  "quantity": {
    "significand": 15,
    "exponent": -1
  }
}
```

--------------------------------

### Valid Money Instance: Robux (X-RBX)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Example of a valid monetary instance for Robux, using a custom currency code.

```json
{
  "currency_code": "X-RBX",
  "quantity": {
    "significand": 2500,
    "exponent": 0
  }
}
```

--------------------------------

### Valid Decimal Instance Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Demonstrates a valid JSON object conforming to the Decimal schema with a significand of 17 and an exponent of 0.

```json
{
  "significand": 17,
  "exponent": 0
}
```

--------------------------------

### Long-Running Operation (WriteBook)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

Demonstrates initiating a long-running operation to write a book and then checking its status. The first snippet starts the operation, and the second retrieves its status.

```HTTP
POST /v1/publishers/acme/books:write
{title: "New Book"}
→ {name: "operations/123...", done: false}
```

```HTTP
GET /v1/operations/123...
→ {name: "...", metadata: {...}, done: true, response: {...}}
```

--------------------------------

### WriteBookMetadata Proto Definition

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

Defines the WriteBookMetadata message, including start time, progress, and state for LROs.

```proto
message WriteBookMetadata {
  google.protobuf.Timestamp start_time = 1;
  int32 progress_percent = 2;

  enum State {
    STATE_UNSPECIFIED = 0;
    RUNNING = 1;
    CANCELLING = 2;
    CANCELLED = 3;
    FAILED = 4;
  }

  State state = 3;
}
```

--------------------------------

### Example API Response (Protocol Buffers to JSON)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Illustrates how a Protocol Buffer message is serialized into a JSON object for REST API responses, showing field name conversion and array handling.

```json
{
  "name": "publishers/acme-books/books/learning-go",
  "title": "Learning Go",
  "authors": ["John Doe", "Jane Smith"],
  "rating": 4.5,
  "price": {
    "currencyCode": "USD",
    "quantity": {
      "significand": 4999,
      "exponent": -2
    }
  }
}
```

--------------------------------

### Money Type Examples

Source: https://github.com/aip-dev/aip.dev/blob/main/common-components/schemas/type/money.md

Illustrates how to represent amounts of money using the Money type, including ISO 4217 codes and API-defined extensions.

```json
Five US dollars === {currency_code: "USD", quantity: {significand: 5}}
```

```json
One and a half Bitcoin ===
  {currency_code: "X-BTC", quantity: {significand: 15, exponent: -1}}
```

--------------------------------

### Example: Five US Dollars

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/types.md

Represents five US dollars using the Money type. Requires 'currency_code' and 'quantity' fields.

```json
{currency_code: "USD", quantity: {significand: 5}}
```

--------------------------------

### Valid Large Exponent Decimal Instance Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Illustrates a valid Decimal instance with a large positive exponent, representing 33.5 million.

```json
{
  "significand": 335,
  "exponent": 5
}
```

--------------------------------

### Example: One and a Half Bitcoin

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/types.md

Represents one and a half Bitcoin using a custom currency code 'X-BTC' and a Decimal quantity with an exponent.

```json
{currency_code: "X-BTC", quantity: {significand: 15, exponent: -1}}
```

--------------------------------

### Example ETag Header in Response

Source: https://github.com/aip-dev/aip.dev/blob/main/aip/general/0154/aip.md

A server may provide an ETag header when retrieving a single resource to indicate its current state.

```http
200 OK
Content-type: application/json
ETag: "55cc0347-66fc-46c3-a26f-98a9a7d61d0e"
```

--------------------------------

### Example Weak ETag Header in Response

Source: https://github.com/aip-dev/aip.dev/blob/main/aip/general/0154/aip.md

Weak ETags, used for equivalent but not necessarily byte-for-byte identical resources, must be prefixed with 'W/'.

```http
200 OK
Content-type: application/json
ETag: W/"55cc0347-66fc-46c3-a26f-98a9a7d61d0e"
```

--------------------------------

### Valid Negative Decimal Instance Example

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Shows a valid JSON object for the Decimal schema, representing -0.005 with a significand of -5 and an exponent of -3.

```json
{
  "significand": -5,
  "exponent": -3
}
```

--------------------------------

### Custom Methods

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Custom operations on resources use the colon (`:`) notation, following the pattern `{resource=pattern}:operation`. Examples include archive, undelete, cancel, add, remove, search, and batchGet.

```APIDOC
## POST /v1/{resource=publishers/*/books/*}:archive

### Description
Performs a custom operation on a resource, such as archiving.

### Method
POST

### Endpoint
/v1/{resource=publishers/*/books/*}:archive

### Parameters
#### Path Parameters
- **resource** (string) - Required - The resource name on which to perform the custom operation, following the pattern `publishers/*/books/*`.

### Example Custom Operations:
- `:archive`: Soft delete or move to archive.
- `:undelete`: Restore deleted resource.
- `:cancel`: Cancel operation.
- `:addX`: Add a sub-resource.
- `:removeX`: Remove a sub-resource.
- `:search`: Search resources under a parent.
- `:batchGet`: Get multiple resources under a parent.
```

--------------------------------

### Invalid Money Instance: Custom Currency Code Prefix

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

Example of an invalid monetary instance where a custom currency code does not start with 'X-'.

```json
{
  "currency_code": "BTC",
  "quantity": {
    "significand": 15,
    "exponent": -1
  }
}
```

--------------------------------

### Book Resource Definition (Protocol Buffers)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/types.md

Defines the structure of a Book resource, including its fields and an enum for its format. This definition is used as an example across AIP guidelines.

```proto
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string name = 1;
  string isbn = 2;
  string title = 3;
  repeated string authors = 4;
  float rating = 5;

  enum Format {
    FORMAT_UNSPECIFIED = 0;
    HARDBACK = 1;
    PAPERBACK = 2;
    EBOOK = 3;
    AUDIOBOOK = 4;
  }

  Format format = 6;
}
```

--------------------------------

### Example TranslateText Response

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/service-definitions.md

An example JSON response from the translateText endpoint, showing translated text and detected language.

```json
{
  "translatedText": "Hola mundo. Buenos días",
  "detectedLanguageCode": "en"
}
```

--------------------------------

### Basic Resource Pattern Syntax

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Illustrates the general hierarchical structure of resource names.

```text
{resource}/{id}/{child_resource}/{child_id}
```

--------------------------------

### Get Resource

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Retrieves a single resource by its name. This method follows the pattern `{name=parent/*/child/*}` and is typically implemented as an HTTP GET request.

```APIDOC
## GET /v1/{name=publishers/*/books/*}

### Description
Retrieves a single resource by name.

### Method
GET

### Endpoint
/v1/{name=publishers/*/books/*}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the resource to retrieve, following the pattern `publishers/*/books/*`.
```

--------------------------------

### Invalid Decimal Instance Example (Missing Field)

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/json-schema-reference.md

An example of an invalid JSON object for the Decimal schema, missing the required 'exponent' field.

```json
{
  "significand": 17
}
```

--------------------------------

### Protocol Buffer Library Service Imports

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/README.md

Standard imports for the Library Service, including annotations, client configuration, field behavior, resource definitions, operations, and timestamps.

```proto
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/timestamp.proto";
```

--------------------------------

### Implement GetBook RPC Method

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/proto-definitions.md

This snippet defines a GetBook RPC method for a Library service. It includes HTTP annotations for routing and specifies the method signature and resource reference for the request.

```proto
syntax "proto3";

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

service Library {
  // Get a single book.
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{name=publishers/*/books/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message to get a single book.
message GetBookRequest {
  // The name of the book to retrieve.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/Book"
    }];
}

// A representation of a single book.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  // The name of the book.
  // Format: publishers/{publisher}/books/{book}
  string name = 1;

  // The ISBN (International Standard Book Number) for this book.
  string isbn = 2;

  // The title of the book.
  string title = 3;

  // The author or authors of the book.
  repeated string authors = 4;

  // The rating assigned to the book.
  float rating = 5;
}
```

--------------------------------

### Get a Resource

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

Retrieves a specific resource by its identifier.

```APIDOC
## GET /v1/publishers/{publisherId}/books/{bookId}

### Description
Retrieves a specific book resource.

### Method
GET

### Endpoint
/v1/publishers/{publisherId}/books/{bookId}

### Response
#### Success Response (200)
- **name** (string) - The name of the book.
- **title** (string) - The title of the book.
- **authors** (array) - A list of authors for the book.
- **rating** (number) - The rating of the book.
```

--------------------------------

### Polling Operation Endpoint

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/endpoints.md

Example of how to poll a long-running operation using its unique identifier.

```http
GET /v1/projects/{project}/locations/global/operations/{operation}
```

--------------------------------

### GetBook

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/DOCUMENTATION_INDEX.txt

Retrieves a specific book resource by its name. This endpoint follows the Standard Get method pattern.

```APIDOC
## GET /v1/{name=publishers/*/books/*}

### Description
Retrieves a specific book resource.

### Method
GET

### Endpoint
/v1/{name=publishers/*/books/*}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the book to retrieve, in the format `publishers/*/books/*`.
```

--------------------------------

### Method Signature Recommendation

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Specifies a google.api.method_signature option in Protocol Buffers to recommend simplified client library method signatures.

```proto
rpc GetBook(GetBookRequest) returns (Book) {
  option (google.api.method_signature) = "name";
}
```

--------------------------------

### Implement ListBooks RPC Method with Pagination

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/proto-definitions.md

This snippet defines a ListBooks RPC method for a Library service, including HTTP annotations for routing and pagination details. It specifies the method signature and resource reference for the request.

```proto
syntax "proto3";

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

service Library {
  // Get a single book.
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=publishers/*}/books"
    };
    option (google.api.method_signature) = "parent";
  }
}

// Request message to list a collection of books.
message ListBooksRequest {
  // The publisher to list books for.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The maximum number of books to return.
  // The service may send fewer.
  int32 max_page_size = 2;

  // The page token.
  // If a `next_page_token` value was received on a previous
  // ListBooks call, providing it here will return the next page.
  string page_token = 3;
}

// Response message for listing a collection of books.
message ListBooksResponse {
  // The books under the umbrella of the given publisher.
  repeated Book results = 1;

  // The token to retrieve the next page. This is populated if and only if
  // there are more pages.
  string next_page_token = 2;
}

// A representation of a single book.
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  // The name of the book.
  // Format: publishers/{publisher}/books/{book}
  string name = 1;

  // The ISBN (International Standard Book Number) for this book.
  string isbn = 2;

  // The title of the book.
  string title = 3;

  // The author or authors of the book.
  repeated string authors = 4;

  // The rating assigned to the book.
  float rating = 5;
}
```

--------------------------------

### Protocol Buffer Translation Service Imports

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/README.md

Imports for the Translation Service, focusing on annotations and field behavior.

```proto
import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
```

--------------------------------

### List Resources with Pagination

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/00_START_HERE.md

Lists resources with support for pagination using page size and token.

```APIDOC
## GET /v1/publishers/{publisherId}/books

### Description
Lists book resources with pagination support.

### Method
GET

### Endpoint
/v1/publishers/{publisherId}/books

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - The number of resources to return per page.
- **pageToken** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **results** (array) - A list of book resources.
- **nextPageToken** (string) - A token to retrieve the next page of results. An empty string indicates the last page.
```

--------------------------------

### List Method Proto Definition

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/resource-patterns.md

Defines the protobuf structure for a List method, including the HTTP GET mapping and pagination parameters.

```proto
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books"
  };
}
```

--------------------------------

### Add/Remove Sub-resource Pattern

Source: https://github.com/aip-dev/aip.dev/blob/main/_autodocs/aip-guidelines-overview.md

Adds or removes sub-resources from a collection within a parent resource. For example, adding or removing an author from a book.

```APIDOC
## POST /v1/{resource=publishers/*/books/*}:addAuthor
## POST /v1/{resource=publishers/*/books/*}:removeAuthor

### Description
This pattern allows for adding or removing sub-resources from a collection within a parent resource. For instance, managing authors associated with a book.

### Method
POST

### Endpoint
/v1/{resource=publishers/*/books/*}:addAuthor
/v1/{resource=publishers/*/books/*}:removeAuthor

### Parameters
#### Path Parameters
- **resource** (string) - Required - The parent resource identifier, e.g., `publishers/*/books/*`.

#### Request Body (Add Author)
- **book** (string) - Required - The parent book resource.
- **author** (string) - Required - The author identifier to add.

### Response
#### Success Response (200)
- **Book** (object) - The updated book resource with the author added or removed.
```