From 959a4fd9ec2e533f668fff61f28d9ee77ddaf6fe Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Tue, 11 Nov 2025 10:24:46 -0800 Subject: [PATCH] feat(examples): use aep.api.resource now that aep.api.resource exists, it can serve as the source of truth instead of google.api.resource. --- aep/general/0004/aep.md.j2 | 4 +-- aep/general/0008/aep.md.j2 | 2 +- aep/general/0122/aep.md.j2 | 8 +++--- aep/general/0124/embedded_resource.proto | 2 +- aep/general/0124/many_to_many_repeated.proto | 2 +- .../0124/many_to_many_subresource.proto | 2 +- aep/general/0124/multiple_many_to_one.proto | 2 +- aep/general/0126/enum.proto | 2 +- aep/general/0136/library.proto | 2 +- aep/general/0144/add_remove.proto | 2 +- aep/general/0144/aep.md.j2 | 2 +- aep/general/0156/aep.md.j2 | 2 +- aep/general/0164/undelete.proto | 2 +- aep/general/0180/aep.md.j2 | 6 ++--- aep/general/0214/aep.md.j2 | 2 +- aep/general/example.oas.yaml | 8 ++++-- aep/general/example.proto | 26 +++++++++---------- 17 files changed, 40 insertions(+), 36 deletions(-) diff --git a/aep/general/0004/aep.md.j2 b/aep/general/0004/aep.md.j2 index 59b4f3bf..54c7b369 100644 --- a/aep/general/0004/aep.md.j2 +++ b/aep/general/0004/aep.md.j2 @@ -47,12 +47,12 @@ APIs **must** annotate the resource types for each resource in the API {% tab proto %} -For protobuf, use the [`google.api.resource`][resource] annotation: +For protobuf, use the [`aep.api.resource`][resource] annotation: ```proto // A representation of a user event. message UserEvent { - option (google.api.resource) = { + option (aep.api.resource) = { type: "user.example.com/user-event" singular: "user-event" plural: "user-events" diff --git a/aep/general/0008/aep.md.j2 b/aep/general/0008/aep.md.j2 index a79fef8d..5b850503 100644 --- a/aep/general/0008/aep.md.j2 +++ b/aep/general/0008/aep.md.j2 @@ -44,7 +44,7 @@ clients or their authors, including but not limited to: Examples of enhancements include: - Requiring new proto annotations that enable more descriptive interfaces on - clients (e.g. requiring `singular` and `plural` on a `google.api.resource` + clients (e.g. requiring `singular` and `plural` on a `aep.api.resource` annotation). AEP guidance **must not** be a significant detriment to a client's usability or diff --git a/aep/general/0122/aep.md.j2 b/aep/general/0122/aep.md.j2 index da4c5841..07f2919a 100644 --- a/aep/general/0122/aep.md.j2 +++ b/aep/general/0122/aep.md.j2 @@ -191,13 +191,13 @@ and the full resource path does not change between these. When defining a resource, the first field **should** be the resource path, which **must** be of type `string` and **must** be called `path` for the -resource path. The message **should** include a `google.api.resource` -annotation declaring the type (see AEP-4 for more on this). +resource path. The message **should** include a `aep.api.resource` annotation +declaring the type (see AEP-4 for more on this). ```proto // A representation of a book in the library. message Book { -option (google.api.resource) = { +option (aep.api.resource) = { type: "apis.example.com/library/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; @@ -296,7 +296,7 @@ When referencing a resource path for a different resource: ```proto // A representation of a book in a library. message Book { -option (google.api.resource) = { +option (aep.api.resource) = { type: "apis.example.com/library/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0124/embedded_resource.proto b/aep/general/0124/embedded_resource.proto index b425dece..13213a58 100644 --- a/aep/general/0124/embedded_resource.proto +++ b/aep/general/0124/embedded_resource.proto @@ -6,7 +6,7 @@ import "google/api/resource.proto"; message Book { // The resource path pattern for Book indicates that Publisher is the // canonical parent. - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0124/many_to_many_repeated.proto b/aep/general/0124/many_to_many_repeated.proto index 505ebee2..898a92ed 100644 --- a/aep/general/0124/many_to_many_repeated.proto +++ b/aep/general/0124/many_to_many_repeated.proto @@ -5,7 +5,7 @@ import "google/api/field_behavior.proto"; import "google/api/resource.proto"; message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0124/many_to_many_subresource.proto b/aep/general/0124/many_to_many_subresource.proto index 7bd0510f..1b561e96 100644 --- a/aep/general/0124/many_to_many_subresource.proto +++ b/aep/general/0124/many_to_many_subresource.proto @@ -7,7 +7,7 @@ import "google/api/resource.proto"; message BookAuthor { // The resource pattern for BookAuthor indicates that Book is the // canonical parent. - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/BookAuthor" pattern: "publishers/{publisher_id}/books/{book_id}/authors/{book_author}" }; diff --git a/aep/general/0124/multiple_many_to_one.proto b/aep/general/0124/multiple_many_to_one.proto index 6c85d54d..511676aa 100644 --- a/aep/general/0124/multiple_many_to_one.proto +++ b/aep/general/0124/multiple_many_to_one.proto @@ -6,7 +6,7 @@ import "google/api/resource.proto"; message Book { // The resource path pattern for Book indicates that Publisher is the // canonical parent. - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0126/enum.proto b/aep/general/0126/enum.proto index cb854680..268ca109 100644 --- a/aep/general/0126/enum.proto +++ b/aep/general/0126/enum.proto @@ -18,7 +18,7 @@ import "google/api/resource.proto"; // A representation of a book. message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0136/library.proto b/aep/general/0136/library.proto index 3d981740..67434dcc 100644 --- a/aep/general/0136/library.proto +++ b/aep/general/0136/library.proto @@ -73,7 +73,7 @@ message SortBooksResponse {} // A representation of a single book. message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0144/add_remove.proto b/aep/general/0144/add_remove.proto index 71969f18..01e62b9b 100644 --- a/aep/general/0144/add_remove.proto +++ b/aep/general/0144/add_remove.proto @@ -48,7 +48,7 @@ message RemoveAuthorRequest { // A representation of a single book. message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0144/aep.md.j2 b/aep/general/0144/aep.md.j2 index 3b28864d..eeef5107 100644 --- a/aep/general/0144/aep.md.j2 +++ b/aep/general/0144/aep.md.j2 @@ -13,7 +13,7 @@ Resources **may** use array fields where appropriate. ```proto message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0156/aep.md.j2 b/aep/general/0156/aep.md.j2 index 3d032738..f8a13efb 100644 --- a/aep/general/0156/aep.md.j2 +++ b/aep/general/0156/aep.md.j2 @@ -16,7 +16,7 @@ For example: ```proto message Config { - option (google.api.resource) = { + option (aep.api.resource) = { type: "api.example.com/Config" pattern: "users/{user}/config" }; diff --git a/aep/general/0164/undelete.proto b/aep/general/0164/undelete.proto index f80ce1c5..654abf92 100644 --- a/aep/general/0164/undelete.proto +++ b/aep/general/0164/undelete.proto @@ -42,7 +42,7 @@ message UndeleteBookRequest { // A representation of a single book. message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "library.googleapis.com/Book" pattern: "publishers/{publisher_id}/books/{book_id}" }; diff --git a/aep/general/0180/aep.md.j2 b/aep/general/0180/aep.md.j2 index 4f1bdebc..180e6404 100644 --- a/aep/general/0180/aep.md.j2 +++ b/aep/general/0180/aep.md.j2 @@ -148,7 +148,7 @@ For example: ```proto message Book { - // google.api.resource and other annotations and fields + // aep.api.resource and other annotations and fields // The genre of the book // If this is not set when the book is created, the field will be given a value of FICTION. @@ -164,7 +164,7 @@ Changing to: ```proto message Book { - // google.api.resource and other annotations and fields + // aep.api.resource and other annotations and fields // The genre of the book // If this is not set when the book is created, the field will be given a value of NONFICTION. @@ -192,7 +192,7 @@ Consider the following proto, where the default value of `wheels` is `2`: ```proto // A representation of an automobile message Automobile { - // google.api.resource and other annotations and fields + // aep.api.resource and other annotations and fields // The number of wheels on the automobile. // The default value is 2, when no value is sent by the client. diff --git a/aep/general/0214/aep.md.j2 b/aep/general/0214/aep.md.j2 index 5bc66a70..7bad813a 100644 --- a/aep/general/0214/aep.md.j2 +++ b/aep/general/0214/aep.md.j2 @@ -33,7 +33,7 @@ library. ```proto message ExpiringResource { - // google.api.resource and other annotations and fields + // aep.api.resource and other annotations and fields oneof expiration { // Timestamp in UTC of when this resource is considered expired. diff --git a/aep/general/example.oas.yaml b/aep/general/example.oas.yaml index 8a662064..024f3683 100644 --- a/aep/general/example.oas.yaml +++ b/aep/general/example.oas.yaml @@ -7,10 +7,8 @@ components: properties: family_name: type: string - x-aep-field-number: 2 given_name: type: string - x-aep-field-number: 1 type: object type: array edition: @@ -43,6 +41,7 @@ components: - publishers/{publisher_id}/books/{book_id} plural: books singular: book + type: bookstore.example.com/book book-edition: properties: display_name: @@ -62,6 +61,7 @@ components: - publishers/{publisher_id}/books/{book_id}/editions/{book_edition_id} plural: book-editions singular: book-edition + type: bookstore.example.com/book-edition isbn: properties: path: @@ -75,6 +75,7 @@ components: - isbns/{isbn_id} plural: isbns singular: isbn + type: bookstore.example.com/isbn item: properties: book: @@ -101,6 +102,7 @@ components: - stores/{store_id}/items/{item_id} plural: items singular: item + type: bookstore.example.com/item publisher: properties: description: @@ -116,6 +118,7 @@ components: - publishers/{publisher_id} plural: publishers singular: publisher + type: bookstore.example.com/publisher store: properties: description: @@ -135,6 +138,7 @@ components: - stores/{store_id} plural: stores singular: store + type: bookstore.example.com/store info: contact: email: aepsupport@aep.dev diff --git a/aep/general/example.proto b/aep/general/example.proto index e51b52f3..4eb36e1a 100644 --- a/aep/general/example.proto +++ b/aep/general/example.proto @@ -5,10 +5,10 @@ package example.bookstore.v1; import "aep/api/field_info.proto"; import "aep/api/operation.proto"; +import "aep/api/resource.proto"; import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; -import "google/api/resource.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/field_mask.proto"; @@ -274,11 +274,11 @@ service Bookstore { // A Book. message Book { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/book" pattern: ["publishers/{publisher_id}/books/{book_id}"] - plural: "books" singular: "book" + plural: "books" }; // A Author. @@ -331,11 +331,11 @@ message Book { // A BookEdition. message BookEdition { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/book-edition" pattern: ["publishers/{publisher_id}/books/{book_id}/editions/{book_edition_id}"] - plural: "book-editions" singular: "book-edition" + plural: "book-editions" }; // Field for display_name. @@ -353,11 +353,11 @@ message BookEdition { // A Isbn. message Isbn { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/isbn" pattern: ["isbns/{isbn_id}"] - plural: "isbns" singular: "isbn" + plural: "isbns" }; // Field for path. @@ -366,11 +366,11 @@ message Isbn { // A Item. message Item { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/item" pattern: ["stores/{store_id}/items/{item_id}"] - plural: "items" singular: "item" + plural: "items" }; // Field for book. @@ -398,11 +398,11 @@ message Item { // A Publisher. message Publisher { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/publisher" pattern: ["publishers/{publisher_id}"] - plural: "publishers" singular: "publisher" + plural: "publishers" }; // Field for description. @@ -414,11 +414,11 @@ message Publisher { // A Store. message Store { - option (google.api.resource) = { + option (aep.api.resource) = { type: "bookstore.example.com/store" pattern: ["stores/{store_id}"] - plural: "stores" singular: "store" + plural: "stores" }; // Field for name.