Skip to main content
Version: 4.x

Migration from v2

This guide lists the breaking changes between v2 and v3 of UnambitiousFx.Functional.

ASP.NET Core: 401 and 403 are no longer swapped​

In v2, DefaultFailureHttpMapper answered UnauthorizedFailure with 401 and UnauthenticatedFailure with 403. v3 follows RFC 9110 and the ASP.NET Core convention (Results.Challenge() → 401, Results.Forbid() → 403):

Failure typev2v3
UnauthenticatedFailure403 Forbidden401 Unauthorized
UnauthorizedFailure401 Unauthorized403 Forbidden

The ProblemDetails bodies change with them:

  • UnauthenticatedFailure: title "Unauthorized", type https://www.rfc-editor.org/rfc/rfc9110#section-15.5.2.
  • UnauthorizedFailure: title "Forbidden", type https://www.rfc-editor.org/rfc/rfc9110#section-15.5.4.

What to do:

  • If you registered your own mappers only to get the conventional 401/403 split, you can remove them.
  • If your clients rely on the v2 statuses, register typed mappers to keep them:
services.AddResultHttp(options =>
{
options.AddMapper<UnauthorizedFailure>(StatusCodes.Status401Unauthorized);
options.AddMapper<UnauthenticatedFailure>(StatusCodes.Status403Forbidden);
});

ASP.NET Core: ValidationFailure answers 422​

In v2, DefaultFailureHttpMapper answered every ValidationFailure with 400 Bad Request. v3 answers 422 Unprocessable Content (RFC 9110 §15.5.21): the request was parsed and bound, then a rule refused it. 400 is left for requests that cannot be read, such as a BadRequestFailure or an ASP.NET Core model-binding error.

Failure typev2v3
ValidationFailure400 Bad Request422 Unprocessable Content
BadRequestFailure400 Bad Request400 Bad Request

The body is unchanged apart from status and type (https://www.rfc-editor.org/rfc/rfc9110#section-15.5.21).

What to do: if your clients test for 400, keep it with ValidationStatus, which covers every ValidationFailure whatever its code and keeps errors:

services.AddResultHttp(options => options.ValidationStatus(StatusCodes.Status400BadRequest));

ASP.NET Core: problem types cite RFC 9110​

The type URIs written by DefaultFailureHttpMapper pointed at RFC 7231, which RFC 9110 obsoletes. They now point at RFC 9110:

Statusv2v3
400https://tools.ietf.org/html/rfc7231#section-6.5.1https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1
404https://tools.ietf.org/html/rfc7231#section-6.5.4https://www.rfc-editor.org/rfc/rfc9110#section-15.5.5
409https://tools.ietf.org/html/rfc7231#section-6.5.8https://www.rfc-editor.org/rfc/rfc9110#section-15.5.10
422—https://www.rfc-editor.org/rfc/rfc9110#section-15.5.21
500https://tools.ietf.org/html/rfc7231#section-6.6.1https://www.rfc-editor.org/rfc/rfc9110#section-15.6.1

What to do: update clients that compare type against the RFC 7231 URIs.

See also​