Endpoints
This convention explains how to expose endpoints from an API built on Anarchy.Toolkit.Web, with clear boundaries and low coupling. The objective is to keep HTTP contracts stable while allowing domain models to evolve independently.
Recommendation, not a requirement. The packages work without following this convention. It is a rule only for code in the toolkit repository (see Contributing); applications can adopt it, adapt it or skip it. Opting out or adapting explains how.
Why
Separate presentation DTOs keep HTTP contracts stable while domain types change, and keep Web concerns out of Core, as layering requires.
The toolkit follows these rules itself (see HealthController and the Health*Output DTOs in Anarchy.Toolkit.Web), and applications built on it may use them as a starting point. The examples below use a User resource from a user-management API.
Recommended project structure
Use the same layers as the toolkit (see Layered Architecture):
src/
└── Library/
├── Core/
│ └── Entity/
│ ├── DomainModel/
│ │ ├── UserEntity.cs
│ │ └── UserRoleEntity.cs
│ └── Api/
│ ├── Input/
│ │ └── CreateUserUseCaseInput.cs
│ └── Output/
│ └── UserAuditDto.cs
└── Web/
└── Presentation/
├── Contract/
│ └── User/
│ └── IUserController.cs
└── Entity/
├── Input/
│ └── CreateUserInput.cs
└── Output/
├── UserOutput.cs
└── UserAuditOutput.cs
What each layer owns
Core/Entity/DomainModel: internal business state and behavior. Keep it free to evolve without forcing HTTP contract changes.Core/Entity/Api/Input: service/use-case inputs when arguments are complex and do not map to a single domain entity.Core/Entity/Api/Output: DTOs produced by services when combining several domain sources (in the toolkit,HealthCheckReportandExceptionReportinAnarchy.Toolkit.Core.Health.Reportsplay this role).Web/Presentation/Contract: endpoint routes and signatures. One stable contract surface helps tests and client integrations. Controller contracts may extend the toolkit’sIToolkitControllermarker.Web/Presentation/Entity/InputandWeb/Presentation/Entity/Output: HTTP request/response shapes owned by the presentation layer. Output DTOs also own their own Core-to-DTO mapping (see below); there is no separateWeb/Service/Builderlayer.
Endpoint rules
- Every endpoint must declare explicit response types (
ProducesResponseType) using Web entities. - Use
ActionResult<T>for endpoints that return payloads. This enforces type safety at the interface level and improves API documentation. For example,Task<ActionResult<UserOutput>>makes the contract explicit. - Only use bare
IActionResultfor endpoints without a response body (e.g.204 No Content,202 Accepted). - Never expose Core domain entities (or Core
ApiDTOs) in response payloads. Every response payload must be a dedicated Web*Outputtype underWeb/Presentation/Entity/Output, even when its shape mirrors a Core entity/DTO one-to-one. - Never accept Core domain entities (or Core
ApiDTOs) as controller parameters. Every non-primitive request payload ([FromBody], or an implicit-body complex parameter) must be a dedicated Web*Inputtype underWeb/Presentation/Entity/Input. Route/query parameters may stay primitive (string,long,int,double,bool, enums, etc.). - Controllers must never call repositories directly. Call abstraction services such as Use Cases and Entity-based Aggregates.
- Keep controllers thin: validate input, call the service, map output via the DTO’s own static factory method, return a status.
- Only expose fields intentionally meant for API consumers.
- Favor backward-compatible response contracts. Adapt the mapping when internals change, so that internal refactoring does not break API clients.
Mapping Core entities/DTOs to Output DTOs
Do not create separate *Builder classes for this mapping. Add a public static factory method directly on the Output DTO, named FromEntity(...) (when the source is a Core domain entity) or FromDto(...) (when the source is a Core Api/Output DTO).
This is exactly how the toolkit’s health endpoint works:
namespace Anarchy.Toolkit.Web.Presentation.Entity.Output.Health;
public record HealthCheckReportOutput(
bool Passed,
TimeSpan Duration,
IReadOnlyCollection<HealthCheckOutcomeOutput> Tests
)
{
public static HealthCheckReportOutput FromDto(HealthCheckReport dto)
{
return new HealthCheckReportOutput(
Passed: dto.Passed,
Duration: dto.Duration,
Tests: dto.Tests.Select(HealthCheckOutcomeOutput.FromDto).ToArray()
);
}
}
Rules for this mapping:
- The factory method lives on the DTO it produces, not on a separate class. If you find yourself creating a
Web/Service/Builder/Outputfolder, fold that logic into the DTO instead. - When a DTO nests other DTOs (e.g. a collection of items), give each nested DTO its own static factory method and have the parent call it (
Tests = dto.Tests.Select(HealthCheckOutcomeOutput.FromDto).ToArray()), rather than inlining the nested mapping. - Prefer
FromEntitywhen mapping directly from aCore/Entity/DomainModel(/Persisted)entity, andFromDtowhen mapping from aCore/Entity/Api/OutputDTO. - Every
FromEntity/FromDtomethod must have a unit test that mirrors the DTO’s folder (e.g.tests/Unit/Web/Presentation/Entity/Output/Health/HealthCheckReportOutputTest.cs). At minimum, cover field-by-field mapping, nested-collection mapping (count + ordering), and null/optional-field handling.
Mapping Web Input records to Core Input DTOs/entities
Symmetrically, do not map an Input record’s fields inline in the controller body, and do not create a separate mapper class either. Add a public instance method on the Web Input record, named ToDto(...) (target: a Core Api/Input DTO) or ToEntity(...) (target: a Core domain entity). Pass any values the request doesn’t carry itself (e.g. a route id) as method arguments:
public class CreateUserInput
{
[Required] public required string Email { get; init; }
public required IReadOnlyCollection<string> RoleIds { get; init; }
public CreateUserUseCaseInput ToUseCaseParams()
{
return new CreateUserUseCaseInput {
Email = Email,
RoleIds = RoleIds
};
}
}
Rules for this mapping:
- The conversion method lives on the Web Input type itself.
- Name the method for what it produces:
ToDto()/ToUseCaseParams()for a CoreApi/InputDTO,ToEntity()for a Core domain entity. - Controllers call
input.ToEntity(...)/input.ToDto(...)directly in the service call instead of constructing the Core type inline. - Every
ToDto/ToEntity/ToUseCaseParamsmethod must have a unit test mirroring the Input type’s folder, covering field-by-field mapping and optional/default-value fields.
The toolkit’s validation attributes (RequiredIntAttribute, RequiredLongAttribute, RequiredDecimalAttribute, DefinedEnumAttribute in Web/Presentation/Attribute) are meant for these Input records.
Contract-first interfaces in Web
Declare controller interfaces in Web/Presentation/Contract and implement them in API hosts.
Benefits:
- one source of truth for routes and endpoint signatures,
- simpler end-to-end tests against a stable contract surface (
RestApiTestCaseBaseandHttpRouteHelper.FromTemplatebuild requests from those route constants), - easier future generation and maintenance of an official client package,
- lower risk of route drift across hosts.
Using ActionResult<T> for type-safe endpoints
The native ASP.NET Core ActionResult<T> type gives you:
- Type safety: the payload type is explicit in the interface and enforced at compile time.
- Better documentation: Swagger (configured by
RestApiWebAppStartupBase) picks up the response type automatically. - No casting: standard helpers like
Ok(),BadRequest(),NotFound()work without wrapper classes. - Backward compatibility: existing implementations using
Ok(payload)keep working.
When to use ActionResult<T> vs IActionResult
| Scenario | Use |
|---|---|
| Endpoint returns a typed payload (200, 201, etc.) | ActionResult<TPayload> |
| Endpoint returns no body (202, 204, etc.) | IActionResult |
| Endpoint returns multiple unrelated types | IActionResult |
public interface IUserController : IToolkitController
{
// Returns a payload: use ActionResult<T>
Task<ActionResult<UserOutput>> GetByIdAsync(string id);
// No response body: use IActionResult
Task<IActionResult> DeleteAsync(string id);
}
Recommended endpoint flow
- Receive and validate the transport input (
Web/Presentation/Entity/Input). - Convert it to a use-case/service input (
Core/Entity/Api/Input) or a Core entity via the Input record’s ownToDto()/ToEntity()method. - Execute the service/application logic through abstractions (Use Cases / Aggregates), never repositories from controllers.
- Map the domain/service output to
Web/Presentation/Entity/Outputvia the Output DTO’s ownFromEntity()/FromDto()method. - Return explicit status codes and typed responses.
Unhandled exceptions are translated centrally by the toolkit’s ExceptionMiddleware: InvalidOperationException and JsonException become 400 Bad Request, everything else becomes 500 with an exception report body. Expected outcomes such as “not found” are part of the contract, so return them explicitly from the controller (NotFound()) instead of relying on the middleware. Endpoints that must handle exceptions themselves can opt out with [IgnoreExceptionHandling].
Controller example
[Route(IUserController.RouteBase)]
[Produces("application/json")]
public class UserController(IUserUseCase useCase) : ControllerBase, IUserController
{
[HttpPost]
[Route(IUserController.RouteCreate)]
[ProducesResponseType(typeof(UserOutput), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<UserOutput>> CreateAsync([FromBody] CreateUserInput input)
{
var result = await useCase.CreateAsync(input.ToUseCaseParams());
var output = UserOutput.FromDto(result);
return CreatedAtAction(nameof(GetByIdAsync), new { userId = output.Id }, output);
}
[HttpGet]
[Route(IUserController.RouteGetById)]
[ProducesResponseType(typeof(UserOutput), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<UserOutput>> GetByIdAsync(string userId)
{
var result = await useCase.GetByIdAsync(userId);
return result == null
? NotFound()
: Ok(UserOutput.FromDto(result));
}
}
Opting out or adapting
| You want to… | Do this |
|---|---|
| Return domain types directly | Possible for internal or small APIs; nothing in Web requires DTOs. |
| Use minimal APIs instead of controllers | Fine: the toolkit’s middlewares and startup work with either. |
| Use a mapping library (Mapster, AutoMapper) | Fine: ToDto/FromDto are a convention, not an interface the toolkit calls. |
What you lose by opting out: contracts that survive refactoring the domain, and the clear Web/Core boundary the layering check enforces.