From 244416a3540f20140dca5fef2a8731208115140b Mon Sep 17 00:00:00 2001 From: Slavo Vojacek Date: Sun, 26 May 2024 10:51:13 +0100 Subject: [PATCH] Update readme --- README.md | 230 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 228 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ba60d75..336cfa5 100644 --- a/README.md +++ b/README.md @@ -32,14 +32,240 @@ go install github.com/thames-technology/apigen ## Getting started -Create standard `BookService` definition with `author` parent resource in `proto/bookservice/v1alpha1/service.proto`: +Create `BookService` with `author` parent resource: ```sh apigen proto -r book -p author -pkg bookservice.v1alpha1 -w ``` -Create standard `AuthorService` definition without a parent resource in `proto/authorservice/v1alpha1/service.proto`: +This will generate the following standard API definitions in `proto/bookservice/v1alpha1/service.proto`: + +```proto +syntax = "proto3"; + +package bookservice.v1alpha1; + +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +// ============================================================================= +// Service definition +// ============================================================================= + +// The BookService defines the standard methods for managing books. +service BookService { + // Creates a new book in the library. + rpc CreateBook(CreateBookRequest) returns (CreateBookResponse); + // Retrieves a book by its ID. + rpc GetBook(GetBookRequest) returns (GetBookResponse); + // Lists books with pagination support. + rpc ListBooks(ListBooksRequest) returns (ListBooksResponse); + // Updates an existing book. + rpc UpdateBook(UpdateBookRequest) returns (UpdateBookResponse); + // Deletes a book by its ID. + rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty); +} + +// ============================================================================= +// Service request and response messages +// ============================================================================= + +// Request message for CreateBook method. +message CreateBookRequest { + // The book to be created. + Book book = 1; +} + +// Response message for CreateBook method. +message CreateBookResponse { + // The created book. + Book book = 1; +} + +// Request message for GetBook method. +message GetBookRequest { + // ID of the book to retrieve. + string id = 1; +} + +// Response message for GetBook method. +message GetBookResponse { + // The retrieved book. + Book book = 1; +} + +// Request message for ListBooks method. +message ListBooksRequest { + // The maximum number of books to return. + int32 page_size = 1; + // The token to retrieve the next page of results. + string page_token = 2; + // The ID of the parent resource. + string parent_id = 3; +} + +// Response message for ListBooks method. +message ListBooksResponse { + // The list of books. + repeated Book results = 1; + // Token to retrieve the next page of results. + string next_page_token = 2; + // Estimated total number of results. + int32 total_results_estimate = 3; +} + +// Request message for UpdateBook method. +message UpdateBookRequest { + // The book to be updated. + Book book = 1; + // The field mask specifying the fields to update. + google.protobuf.FieldMask update_mask = 2; +} + +// Response message for UpdateBook method. +message UpdateBookResponse { + // The updated book. + Book book = 1; +} + +// Request message for DeleteBook method. +message DeleteBookRequest { + // ID of the book to delete. + string id = 1; +} + +// ============================================================================= +// Resource messages +// ============================================================================= + +// The Book message represents a book in the library. +message Book { + // Unique identifier for the book. + string id = 1; + // When the book was created. + google.protobuf.Timestamp create_time = 2; + // When the book was last updated. + google.protobuf.Timestamp update_time = 3; + // ID of the author of the book. + string author_id = 4; +} +``` + +Create `AuthorService` definition without a parent resource: ```sh apigen proto -r author -pkg authorservice.v1alpha1 -w ``` + +This will generate the following standard API definitions in `proto/authorservice/v1alpha1/service.proto`: + +```proto +syntax = "proto3"; + +package authorservice.v1alpha1; + +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; +import "google/protobuf/timestamp.proto"; + +// ============================================================================= +// Service definition +// ============================================================================= + +// The AuthorService defines the standard methods for managing authors. +service AuthorService { + // Creates a new author in the library. + rpc CreateAuthor(CreateAuthorRequest) returns (CreateAuthorResponse); + // Retrieves a author by its ID. + rpc GetAuthor(GetAuthorRequest) returns (GetAuthorResponse); + // Lists authors with pagination support. + rpc ListAuthors(ListAuthorsRequest) returns (ListAuthorsResponse); + // Updates an existing author. + rpc UpdateAuthor(UpdateAuthorRequest) returns (UpdateAuthorResponse); + // Deletes a author by its ID. + rpc DeleteAuthor(DeleteAuthorRequest) returns (google.protobuf.Empty); +} + +// ============================================================================= +// Service request and response messages +// ============================================================================= + +// Request message for CreateAuthor method. +message CreateAuthorRequest { + // The author to be created. + Author author = 1; +} + +// Response message for CreateAuthor method. +message CreateAuthorResponse { + // The created author. + Author author = 1; +} + +// Request message for GetAuthor method. +message GetAuthorRequest { + // ID of the author to retrieve. + string id = 1; +} + +// Response message for GetAuthor method. +message GetAuthorResponse { + // The retrieved author. + Author author = 1; +} + +// Request message for ListAuthors method. +message ListAuthorsRequest { + // The maximum number of authors to return. + int32 page_size = 1; + // The token to retrieve the next page of results. + string page_token = 2; + // The ID of the parent resource. + string parent_id = 3; +} + +// Response message for ListAuthors method. +message ListAuthorsResponse { + // The list of authors. + repeated Author results = 1; + // Token to retrieve the next page of results. + string next_page_token = 2; + // Estimated total number of results. + int32 total_results_estimate = 3; +} + +// Request message for UpdateAuthor method. +message UpdateAuthorRequest { + // The author to be updated. + Author author = 1; + // The field mask specifying the fields to update. + google.protobuf.FieldMask update_mask = 2; +} + +// Response message for UpdateAuthor method. +message UpdateAuthorResponse { + // The updated author. + Author author = 1; +} + +// Request message for DeleteAuthor method. +message DeleteAuthorRequest { + // ID of the author to delete. + string id = 1; +} + +// ============================================================================= +// Resource messages +// ============================================================================= + +// The Author message represents a author in the library. +message Author { + // Unique identifier for the author. + string id = 1; + // When the author was created. + google.protobuf.Timestamp create_time = 2; + // When the author was last updated. + google.protobuf.Timestamp update_time = 3; +} +```