wertzui/restworld

Introduce a new API version (V2, V3, ...) of an existing RESTworld endpoint without breaking existing clients. Use when asked to add API versioning, create a v2 of an endpoint, change a DTO in a breaking way (rename or split a property, remove a field), deprecate an old version, keep V1 working, register a pipeline with ApiVersion, use [ApiVersion] on custom controllers, version custom services, authorization handlers or HAL-Forms customizations, set the default version, or understand how clients request a version via the Accept header (application/hal+json; v=2) or query parameter. Uses AuthorDtoV1 / AuthorDto from ExampleBlog as the worked example.

End-to-end checklist for adding a new REST endpoint for a database entity to a RESTworld API. Use when asked to add an endpoint, add a new resource, expose an entity through the API, add CRUD for a table, add a new controller for an entity, scaffold a complete feature (entity, migration, DTOs, mapper, pipeline registration), or when unsure which RESTworld steps and skills to apply in which order. Orchestrates restworld-create-entity-and-dbcontext, restworld-create-dtos, restworld-create-mapper, restworld-choose-pipeline and the optional service, authorization, validation and Angular page skills, and explains how to verify the result by building and calling the API (HAL-Explorer, Swagger).

Add a list, edit or custom page for a RESTworld endpoint to an Angular app that uses @wertzui/ngx-restworld-client. Use when asked to add a page, route, menu entry, list view, edit view, CRUD UI or master/detail page for a RESTworld resource; to choose between rw-list/rw-edit (Reactive Forms, RESTworldListViewComponent) and rw-signal-list/rw-signal-edit (Signal Forms); to compose rw-table, rw-signal-table, rw-form or rw-signal-form in a custom component; to wire app.routes.ts, AppMenu, apiName/rel/uri route parameters or withComponentInputBinding; to load data with RestWorldClientCollection / RestWorldClient (HAL home discovery, getLinkFromHome, getList, fillTemplate, OData parameters); or to bootstrap a client with provideRestWorld in main.ts, proxy.conf.js, npm start or Aspire. Consumer-side only.

Customize the RESTworld Angular client (@wertzui/ngx-restworld-client) in a consuming app. Use when asked to customize the avatar (provideCustomAvatarGenerator, AvatarGenerator, rw-avatar); change the layout or buttons of rw-form / rw-signal-form with the #content, #buttons, #beforeButtons, #afterButtons templates and rw-form-element; customize dropdown, object or extra-tab templates (#inputOptionsSingle, #inputObject, #extraTabs); use rw-image, rw-file, image cropping or file upload; style rows or menus of rw-table; understand column filters and OData filtering; change the PrimeNG theme (providePrimeNG, definePreset, Aura); or find out what is NOT customizable (rw-display / rw-input type mapping has no registry, so build your own component). Consumer-side only.

Use the small cross-cutting features of a RESTworld API. Use when asked about Swagger / OpenAPI / Swagger UI (also per API version), exposing the API as an MCP server (AutoMcp, AddMcpServer, WithAutoMcp, WithOData, MapMcp), CSV export (text/csv), JSON Patch (PATCH application/json-patch+json, create and update in one request), caching options (RESTworld:Caching Get/GetList/GetHistory), concurrency handling (Timestamp, If-Match, 409 Conflict), history endpoints / temporal tables (HasHistory attribute, $at/$from/$to), the RestWorldImage attribute for image upload and cropping, health endpoints (/health/startup, /health/live, /health/ready), OpenTelemetry/OTLP setup, or hiding a parameter from Swagger (SwaggerIgnore). Also handles: telling which of these features is automatic and which needs configuration.

Write and register a RESTworld authorization handler. Use when asked to secure a RESTworld endpoint, restrict which rows a user may see, deny requests with 401/403, change or hide DTO properties per user, require an authenticated user, implement ICrudAuthorizationHandler, IReadAuthorizationHandler or IBasicAuthorizationHandler, derive from CrudAuthorizationHandlerBase, ReadAuthorizationHandlerBase, BasicAuthorizationHandlerBase, UserIsAuthorizedCrudAuthorizationHandler, UserIsAuthorizedReadAuthorizationHandler or UserIsAuthorizedBasicAuthorizationHandler, use IUserAccessor, filter with AuthorizationResult.WithFilter / WithStatus, or register handlers with AddCrudAuthorizationHandler, AddReadAuthorizationHandler, AddBasicAuthorizationHandler, AddCrudPipelineWithAuthorization, AddReadPipelineWithAuthorization, AddCrudPipelineWithCustomServiceAndAuthorization or AddCustomServiceAndAuthorization. Also covers versioned handlers and the DisableAuthorization setting.

Create a new RESTworld solution from scratch. Use when asked to start a new RESTworld API, bootstrap or scaffold a solution, set up the project layout (Api, Business, Common, Data), choose RESTworld NuGet packages (RESTworld.AspNetCore, RESTworld.Business, RESTworld.EntityFrameworkCore, RESTworld.Common, RESTworld.Client.AspNetCore), write the initial Program.cs with AddRestWorld and UseRestWorld, create appsettings.json (connection string, RESTworld section), add an Angular SPA host project with AddRestWorldWithSpaFrontend and UseRestWorldWithSpaFrontend, or wire an Aspire AppHost for local development with SQL Server, health probes and HAL-Explorer links. Mirrors the ExampleBlog sample.

Choose the correct RESTworld pipeline implementation strategy given a description of what to build. Use when asked which pipeline to use, how to implement a RESTworld endpoint, whether to use ReadPipeline vs CrudPipeline, when to create a custom controller, whether to derive from ReadServiceBase or CrudServiceBase, or how to register a pipeline in Program.cs. Also handles: detecting when entity foreign key relationships require a custom service, choosing versioned vs unversioned registration, and aligning a new API version with a prior version implementation.

Create RESTworld DTOs for a given entity. Use when asked to create DTOs, add DTO types, scaffold DTOs, generate Data Transfer Objects, or create CreateDto/UpdateDto/GetFullDto/GetListDto/QueryDto for an entity. Also handles: creating enums used by DTOs, placing DTOs in the correct .Common project, adding foreign key navigation properties, and asking the user which properties to include in the GetListDto.

Create or extend RESTworld Entity Framework Core entities and the DbContext. Use when asked to create an entity, add a database table, add a model class, add a DbSet, create or change a DbContext, derive from DbContextBase, choose between EntityBase / ConcurrentEntityBase / ChangeTrackingEntityBase, add a foreign key or navigation property, make a table temporal (SQL Server history), add seed data with HasData, add an EF Core migration, run dotnet ef, add a design-time DbContext factory, register the database with AddDbContextFactoryWithDefaults, or apply migrations on startup with MigrateDatabaseDuringStartup. Also covers the connection string name, rowversion Timestamp concurrency, CreatedAt/LastChangedBy auditing and where the files belong in the .Data project.

Create and register a RESTworld mapper between an entity and its DTOs. Use when asked to create a mapper, map entity to DTO, write a Mapperly mapper, derive from CrudMapperlyMapperBase or ReadMapperlyMapperBase, implement ICrudMapper / IReadMapper, maintain or migrate legacy AutoMapper code (AddCrudAutoMapper / AddReadAutoMapper) to Mapperly, register a mapper with AddCrudMapper / AddReadMapper / AddCreateMapper / AddUpdateMapper, ignore infrastructure properties (Id, Timestamp, CreatedAt, LastChangedBy), map navigation properties or foreign keys, fix Mapperly diagnostics about unmapped members, or create a separate mapper per API version. Covers every abstract method that must be implemented and which DTO each one maps.

Write a custom RESTworld controller. Use when asked to add an endpoint that does not fit the CRUD/read pipeline (extra routes, aggregated or joined data, non-DB resources, file/image downloads, actions), derive from RestControllerBase or HalControllerBase, build HAL responses with IODataResourceFactory and IResultFactory (CreateOkResultBasedOnOutcomeAsync, CreateCreatedResultBasedOnOutcomeAsync, CreatePagedCollectionResultBasedOnOutcomeAsync, CreateEmptyResultBasedOnOutcome), cache service results with ICacheHelper and CachingOptions (Get, GetList, GetHistory), return errors with IErrorResultFactory, set routes, [ApiVersion], [ProducesResponseType] and ApiConventionMethod, or understand that controllers are discovered automatically and only their service/handler must be registered. Based on MyCustomController and PhotoController of ExampleBlog.

Write a custom RESTworld service by deriving from CrudServiceBase, ReadServiceBase, DbServiceBase or ServiceBase. Use when asked to customize endpoint logic, choose a base class, decide between the On...ing / On...ed hooks (OnCreatingInternalAsync, OnUpdatingInternalAsync, OnDeletingAsync, OnCreatedInternalAsync, OnUpdatedInternalAsync, OnGotSingleInternalAsync) and overriding CreateInternalAsync / UpdateInternalAsync / GetSingleInternalAsync; populate DTO properties not stored in the database (images, files, statistics); change the DbSet used for reading or updating; write a fully custom service method with a public MyMethodAsync wrapping TryExecuteWithAuthorizationAsync or TryExecuteAsync and a private MyMethodInternalAsync; build a service for a custom controller; return ServiceResponse or AuthorizationResult; or register a service with AddCrudPipelineWithCustomService, AddReadPipelineWithCustomService, AddCustomServiceAndAuthorization or AddScoped. Also covers exception translators.

Consume a RESTworld API from .NET code with RESTworld.Client.Net, or host an Angular SPA next to the API with RESTworld.Client.AspNetCore. Use when asked to call a RESTworld API from a worker, console app, MVC/Minimal API or another service; to register AddRestWorldClients; to configure RESTworld:ClientSettings:ApiUrls (Name, Url, Version); to use IRestWorldClient / IRestWorldClientCollection (GetClient, GetListAsync, GetAllPagesListAsync, GetFormListAsync, GetLinkFromHome); to follow HAL links (FollowGetAsync, FollowPostAsync, FollowPutAsync), page through OData lists, create/update/batch-create resources, handle If-Match/Timestamp conflicts or deprecated API versions; or to set up the SPA host with AddRestWorldWithSpaFrontend / UseRestWorldWithSpaFrontend and the SettingsController.

Customize the HAL-FORMS templates that a RESTworld API generates. Use when asked to add an extra form/template to a resource, embed related data as a form, change what a HAL-Forms response contains, implement IFormsResourceGenerationCustomization, call AddFormsResourceGenerationCustomization, fix OData enum values in the Search form (ODataEnumFix), customize a single form property (placeholder, options, read-only) with PropertyTemplateGenerationCustomization, or register AddForeignKeyForFormTo for foreign-key dropdown options. Also handles: understanding when customizations run (list Search form vs. single-resource form), why a customization is registered as singleton, and how foreign-key navigation properties on DTOs produce options links.

Write unit and integration-style tests for a RESTworld application with the RESTworld.Testing package. Use when asked to test a RESTworld service, mapper, authorization handler, validator or custom service; to set up TestBuilder, ITestEnvironment, ITestConfiguration; to use WithInMemoryDatabase, WithSeed, WithUser, WithoutUser, WithCrudService, WithReadService, WithCrudMapper, WithReadMapper, WithCrudAutoMapper, WithAutomapper, WithValidation, WithService, WithSubstitute, WithOptions, WithAction or BuildWithServiceAsSut; or to create a test project for a RESTworld API. Also handles: seeding an in-memory database, faking the current user, substituting dependencies with NSubstitute, and testing authorization/validation outcomes through the real service.

Add custom validation to a RESTworld CRUD endpoint. Use when asked to validate DTOs before or after create/update, reject a request with a 400 validation error, add business-rule checks (uniqueness, limits, immutable fields, cross-field rules), write a validator class, derive from ValidatorBase, CreateValidatorBase or UpdateValidatorBase, return ValidationResults / IValidationResults, register a validator with AddValidator, AddCreateValidator or AddUpdateValidator, understand AddValidationAndErrorHandling, ValidationService or the problem details / errors dictionary returned to the client, or validate collections (ValidateCollectionBeforeCreateAsync etc.).