refactor: Standardize and simplify API endpoint summaries, rename book listing to GetBooks, and condense OpenAPI header descriptions.

aalmada · aalmada · commit 4388d274ec6a · 2025-12-28T15:19:14.000Z
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminAuthorEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminAuthorEndpoints.cs
@@ -14,19 +14,19 @@ public static RouteGroupBuilder MapAdminAuthorEndpoints(this RouteGroupBuilder g
     {
         group.MapPost("/", CreateAuthor)
             .WithName("CreateAuthor")
-            .WithSummary("Create a new author using Wolverine command/handler pattern");
+            .WithSummary("Create a new author");
 
         group.MapPut("/{id:guid}", UpdateAuthor)
             .WithName("UpdateAuthor")
             .WithSummary("Update an author");
 
         group.MapDelete("/{id:guid}", SoftDeleteAuthor)
             .WithName("SoftDeleteAuthor")
-            .WithSummary("Soft delete an author");
+            .WithSummary("Delete an author");
 
         group.MapPost("/{id:guid}/restore", RestoreAuthor)
             .WithName("RestoreAuthor")
-            .WithSummary("Restore a soft deleted author");
+            .WithSummary("Restore a deleted author");
 
         return group;
     }
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminBookEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminBookEndpoints.cs
@@ -29,23 +29,23 @@ public static RouteGroupBuilder MapAdminBookEndpoints(this RouteGroupBuilder gro
     {
         group.MapPost("/", CreateBook)
             .WithName("CreateBook")
-            .WithSummary("Create a new book using Wolverine command/handler pattern");
+            .WithSummary("Create a new book");
 
         group.MapPut("/{id:guid}", UpdateBook)
             .WithName("UpdateBook")
-            .WithSummary("Update a book. Supports optimistic concurrency with If-Match header.");
+            .WithSummary("Update a book");
 
         group.MapDelete("/{id:guid}", SoftDeleteBook)
             .WithName("SoftDeleteBook")
-            .WithSummary("Soft delete a book. Supports optimistic concurrency with If-Match header.");
+            .WithSummary("Delete a book");
 
         group.MapPost("/{id:guid}/restore", RestoreBook)
             .WithName("RestoreBook")
-            .WithSummary("Restore a soft deleted book. Supports optimistic concurrency with If-Match header.");
+            .WithSummary("Restore a deleted book");
 
         group.MapGet("/", GetAllBooks)
             .WithName("GetAllBooksAdmin")
-            .WithSummary("Get all books including soft deleted");
+            .WithSummary("Get all books");
 
         return group;
     }
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminCategoryEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminCategoryEndpoints.cs
@@ -21,19 +21,19 @@ public static RouteGroupBuilder MapAdminCategoryEndpoints(this RouteGroupBuilder
     {
         group.MapPost("/", CreateCategory)
             .WithName("CreateCategory")
-            .WithSummary("Create a new category with optional translations using Wolverine");
+            .WithSummary("Create a new category");
 
         group.MapPut("/{id:guid}", UpdateCategory)
             .WithName("UpdateCategory")
-            .WithSummary("Update a category and its translations");
+            .WithSummary("Update a category");
 
         group.MapDelete("/{id:guid}", SoftDeleteCategory)
             .WithName("SoftDeleteCategory")
-            .WithSummary("Soft delete a category");
+            .WithSummary("Delete a category");
 
         group.MapPost("/{id:guid}/restore", RestoreCategory)
             .WithName("RestoreCategory")
-            .WithSummary("Restore a soft deleted category");
+            .WithSummary("Restore a deleted category");
 
         return group;
     }
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminPublisherEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/Admin/AdminPublisherEndpoints.cs
@@ -14,19 +14,19 @@ public static RouteGroupBuilder MapAdminPublisherEndpoints(this RouteGroupBuilde
     {
         group.MapPost("/", CreatePublisher)
             .WithName("CreatePublisher")
-            .WithSummary("Create a new publisher using Wolverine command/handler pattern");
+            .WithSummary("Create a new publisher");
 
         group.MapPut("/{id:guid}", UpdatePublisher)
             .WithName("UpdatePublisher")
             .WithSummary("Update a publisher");
 
         group.MapDelete("/{id:guid}", SoftDeletePublisher)
             .WithName("SoftDeletePublisher")
-            .WithSummary("Soft delete a publisher");
+            .WithSummary("Delete a publisher");
 
         group.MapPost("/{id:guid}/restore", RestorePublisher)
             .WithName("RestorePublisher")
-            .WithSummary("Restore a soft deleted publisher");
+            .WithSummary("Restore a deleted publisher");
 
         return group;
     }
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/Admin/ProjectionEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/Admin/ProjectionEndpoints.cs
@@ -10,11 +10,11 @@ public static RouteGroupBuilder MapProjectionEndpoints(this RouteGroupBuilder gr
     {
         group.MapPost("/rebuild", RebuildProjections)
             .WithName("RebuildProjections")
-            .WithSummary("Rebuild all async projections from event store");
+            .WithSummary("Rebuild all projections");
 
         group.MapGet("/status", GetProjectionStatus)
             .WithName("GetProjectionStatus")
-            .WithSummary("Get async daemon projection status");
+            .WithSummary("Get projection status");
 
         return group;
     }
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/AuthorEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/AuthorEndpoints.cs
@@ -16,7 +16,7 @@ public static RouteGroupBuilder MapAuthorEndpoints(this RouteGroupBuilder group)
     {
         group.MapGet("/", GetAuthors)
             .WithName("GetAuthors")
-            .WithSummary("Get all active authors")
+            .WithSummary("Get all authors")
             .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));
 
         group.MapGet("/{id:guid}", GetAuthor)
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/BookEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/BookEndpoints.cs
@@ -15,14 +15,14 @@ public static class BookEndpoints
 {
     public static RouteGroupBuilder MapBookEndpoints(this RouteGroupBuilder group)
     {
-        group.MapGet("/search", SearchBooks)
-            .WithName("SearchBooks")
-            .WithSummary("Search books using ngram matching across title, description, publisher, and authors")
+        group.MapGet("/", SearchBooks)
+            .WithName("GetBooks")
+            .WithSummary("Get all books")
             .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(2)));
 
         group.MapGet("/{id:guid}", GetBook)
             .WithName("GetBook")
-            .WithSummary("Get book by ID. Returns ETag header and supports If-None-Match for caching.")
+            .WithSummary("Get book by ID")
             .CacheOutput(policy => policy
                 .Expire(TimeSpan.FromMinutes(5))
                 .SetVaryByHeader("If-None-Match"));
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/CategoryEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/CategoryEndpoints.cs
@@ -19,12 +19,12 @@ public static RouteGroupBuilder MapCategoryEndpoints(this RouteGroupBuilder grou
     {
         group.MapGet("/", GetCategories)
             .WithName("GetCategories")
-            .WithSummary("Get all active categories (localized based on Accept-Language header)")
+            .WithSummary("Get all categories")
             .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));
 
         group.MapGet("/{id:guid}", GetCategory)
             .WithName("GetCategory")
-            .WithSummary("Get category by ID (localized based on Accept-Language header)")
+            .WithSummary("Get category by ID")
             .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));
 
         return group;
diff --git a/src/ApiService/BookStore.ApiService/Endpoints/PublisherEndpoints.cs b/src/ApiService/BookStore.ApiService/Endpoints/PublisherEndpoints.cs
@@ -16,7 +16,7 @@ public static RouteGroupBuilder MapPublisherEndpoints(this RouteGroupBuilder gro
     {
         group.MapGet("/", GetPublishers)
             .WithName("GetPublishers")
-            .WithSummary("Get all active publishers")
+            .WithSummary("Get all publishers")
             .CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));
 
         group.MapGet("/{id:guid}", GetPublisher)
diff --git a/src/ApiService/BookStore.ApiService/Infrastructure/OpenApiTransformerExtensions.cs b/src/ApiService/BookStore.ApiService/Infrastructure/OpenApiTransformerExtensions.cs
@@ -42,7 +42,7 @@ public static OpenApiOptions AddBookStoreApiDocumentation(this OpenApiOptions op
                 Name = "api-version",
                 In = ParameterLocation.Header,
                 Required = false,
-                Description = "API version to use. Defaults to 1.0 if not specified. Example: `1.0`"
+                Description = "API version. Example: `1.0`"
             });
 
             // Add localization header
@@ -51,7 +51,7 @@ public static OpenApiOptions AddBookStoreApiDocumentation(this OpenApiOptions op
                 Name = "Accept-Language",
                 In = ParameterLocation.Header,
                 Required = false,
-                Description = "Preferred language for response content and error messages. Supported values: `en` (English, default), `pt` (Portuguese), `es` (Spanish), `fr` (French), `de` (German)"
+                Description = "Preferred language. Supported: `en`, `pt`, `es`, `fr`, `de`"
             });
 
             // Add correlation ID header
@@ -60,7 +60,7 @@ public static OpenApiOptions AddBookStoreApiDocumentation(this OpenApiOptions op
                 Name = "X-Correlation-ID",
                 In = ParameterLocation.Header,
                 Required = false,
-                Description = "Correlation ID for distributed tracing. Tracks the entire business transaction across services. If not provided, one will be generated and returned in the response. Example: `01234567-89ab-cdef-0123-456789abcdef`"
+                Description = "Correlation ID for tracking requests across the system"
             });
 
             // Add causation ID header
@@ -69,7 +69,7 @@ public static OpenApiOptions AddBookStoreApiDocumentation(this OpenApiOptions op
                 Name = "X-Causation-ID",
                 In = ParameterLocation.Header,
                 Required = false,
-                Description = "Causation ID for distributed tracing. Tracks the immediate cause of this request (e.g., ID of the previous event or command). Use the `X-Event-ID` from a previous response. Example: `01234567-89ab-cdef-0123-456789abcdef`"
+                Description = "Causation ID linking this request to its trigger"
             });
 
             return Task.CompletedTask;
@@ -81,35 +81,12 @@ public static OpenApiOptions AddBookStoreApiDocumentation(this OpenApiOptions op
     static string BuildApiDescription()
     {
         return """
-            Event-sourced book store management system with book search, author, category, and publisher management.
+            Book store management system with search, authors, categories, and publishers.
 
-            ## API Versioning
-            This API uses header-based versioning. Include the `api-version` header in your requests:
-            - **Current Version**: 1.0
-            - **Default Behavior**: If no version is specified, v1.0 is assumed
-            - **Version Header**: `api-version: 1.0`
-
-            ## Localization
-            The API supports multiple languages for content and error messages:
-            - **Supported Languages**: English (en), Portuguese (pt), Spanish (es), French (fr), German (de)
-            - **Default Language**: English (en)
-            - **Language Header**: `Accept-Language: pt` (use ISO 639-1 language codes)
-
-            ## Distributed Tracing
-            The API implements correlation and causation tracking for distributed tracing:
-
-            ### Request Headers
-            - **X-Correlation-ID**: Tracks the entire business transaction across services. If not provided, one will be generated.
-            - **X-Causation-ID**: Tracks the immediate cause of this request (e.g., the ID of the command or event that triggered this call).
-
-            ### Response Headers
-            - **X-Correlation-ID**: Returns the correlation ID used for this request (either provided or generated).
-            - **X-Event-ID**: Returns the unique ID of any event created by this request (for POST, PUT, DELETE operations).
-
-            ### Best Practices
-            - Always include `X-Correlation-ID` when making related API calls to track the full transaction flow
-            - Use the previous response's `X-Event-ID` as the `X-Causation-ID` for subsequent related requests
-            - Store correlation IDs in your logs to enable end-to-end tracing
+            ## Features
+            - Multi-language support (English, Portuguese, Spanish, French, German)
+            - Request tracking with correlation IDs
+            - Optimistic concurrency control for updates
             """;
     }
 }
diff --git a/src/Web/BookStore.Web/Components/Pages/Home.razor b/src/Web/BookStore.Web/Components/Pages/Home.razor
@@ -158,7 +158,7 @@
         
         try
         {
-            pagedBooks = await ApiClient.SearchBooksAsync(
+            pagedBooks = await ApiClient.GetBooksAsync(
                 string.IsNullOrWhiteSpace(searchQuery) ? null : searchQuery,
                 currentPage,
                 pageSize);
diff --git a/src/Web/BookStore.Web/Services/IBookStoreApi.cs b/src/Web/BookStore.Web/Services/IBookStoreApi.cs
@@ -9,10 +9,10 @@ namespace BookStore.Web.Services;
 public interface IBookStoreApi
 {
     /// <summary>
-    /// Search books with optional query and pagination
+    /// Get all books with optional search query and pagination
     /// </summary>
-    [Get("/api/books/search")]
-    Task<PagedListDto<BookDto>> SearchBooksAsync(
+    [Get("/api/books")]
+    Task<PagedListDto<BookDto>> GetBooksAsync(
         [Query] string? q = null,
         [Query] int page = 1,
         [Query] int pageSize = 20,

Original file line number	Diff line number	Diff line change
`@@ -10,11 +10,11 @@ public static RouteGroupBuilder MapProjectionEndpoints(this RouteGroupBuilder gr`
`10`	`10`	`{`
`11`	`11`	`group.MapPost("/rebuild", RebuildProjections)`
`12`	`12`	`.WithName("RebuildProjections")`
`13`		`- .WithSummary("Rebuild all async projections from event store");`
	`13`	`+ .WithSummary("Rebuild all projections");`
`14`	`14`
`15`	`15`	`group.MapGet("/status", GetProjectionStatus)`
`16`	`16`	`.WithName("GetProjectionStatus")`
`17`		`- .WithSummary("Get async daemon projection status");`
	`17`	`+ .WithSummary("Get projection status");`
`18`	`18`
`19`	`19`	`return group;`
`20`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ public static RouteGroupBuilder MapAuthorEndpoints(this RouteGroupBuilder group)`
`16`	`16`	`{`
`17`	`17`	`group.MapGet("/", GetAuthors)`
`18`	`18`	`.WithName("GetAuthors")`
`19`		`- .WithSummary("Get all active authors")`
	`19`	`+ .WithSummary("Get all authors")`
`20`	`20`	`.CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));`
`21`	`21`
`22`	`22`	`group.MapGet("/{id:guid}", GetAuthor)`