You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Conventions useful for creating an ASP.NET Core based REST API on top of a domain model. Specifically, it provides extension methods which convert from domain model types, as defined in [`Winton.DomainModelling.Abstractions`](https://github.com/wintoncode/Winton.DomainModelling.Abstractions) to ASP.NET Core types.
`Result<TData>` is a type defined in the `Winton.DomainModelling.Abstractions` package.
10
+
`Result<TData>` is a type defined in the `Winton.DomainModelling.Abstractions` package.
13
11
It is a type that is intended to be returned from domain operations.
14
12
It allows operations to indicate both successes and failures to the client.
15
13
In this case the client is an ASP.NET Core Controller.
16
14
In a Controller, however, we need to return an `IActionResult` rather than a `Result<TData>`. We have two cases to consider:
15
+
17
16
* If the `Result<TData>` was a success then we want to return a 2xx response from the API containing the data in the body.
18
17
* If the `Result<TData>` was a failure then we want to return a 4xx response from the API containing [problem details](https://tools.ietf.org/html/rfc7807) in the body.
19
18
20
19
This library provides a `ToActionResult` extension method for `Result<TData>` which matches on the result and converts it to an appropriate `IActionResult`.
21
-
There are various overloads to provide flexibility.
20
+
There are various overloads to provide flexibility.
21
+
22
22
It is expected that this will be used within an [`ApiController`](https://docs.microsoft.com/en-us/aspnet/core/web-api/?view=aspnetcore-2.2#annotation-with-apicontroller-attribute) so that ASP.NET Core will apply its REST API conventions to the `IActionResult`.
23
23
24
24
### Successful Result Mappings
@@ -30,7 +30,7 @@ The following default mappings happen when the `Result` is a `Success`.
The defaults can be overriden by calling the extension method that takes a success mapping function.
33
+
The defaults can be overriden by calling the extension method that takes a success mapping function.
34
34
A common example of when this is used is in a `POST` action when an entity has been created and we would like to return a 201 Created response to the client.
35
35
36
36
```csharp
@@ -48,8 +48,9 @@ public async Task<IActionResult> CreateFoo(NewFoo newFoo)
48
48
49
49
The `CreateFoo` method performs the domain logic to create a new `Foo` and returns `Result<Foo>`.
50
50
51
-
*In a real application it would be defined in the domain model project.
52
-
To give the domain model an API which is defined in terms of commands and queries and to decouple it from the outer application layers the mediator pattern is often adopted.
51
+
*In a real application it would be defined in the domain model project.
52
+
To give the domain model an API which is defined in terms of commands and queries and to decouple it from the outer application layers the mediator pattern is often adopted.
53
+
53
54
Jimmy Bogard's [MediatR](https://github.com/jbogard/MediatR) is a useful library for implementing that pattern.*
54
55
55
56
### Failure Result Mappings
@@ -66,13 +67,13 @@ The following table shows the default mappings.
66
67
67
68
_*This includes any other types that inherit from `Error` and are not explicitly listed._
68
69
69
-
The defaults can be overriden by calling the extension method that takes an error mapping function.
70
+
The defaults can be overriden by calling the extension method that takes an error mapping function.
70
71
This is useful when the domain model has defined additional error types and these need to be converted to the relevant problem details.
71
72
The status code that is set on the `ProblemDetails` will also be set on the `IActionResult` by the extension method so that the HTTP status code on the response is correct.
72
73
73
-
For example consider a domain model that deals with payments.
74
-
It could be a news service which requires a subscription to access content.
75
-
It might contain several operations that require payment to be made before they can proceed.
74
+
For example consider a domain model that deals with payments.
75
+
It could be a news service which requires a subscription to access content.
76
+
It might contain several operations that require payment to be made before they can proceed.
76
77
This domain may therefore define a new error type as follows:
77
78
78
79
```csharp
@@ -85,7 +86,7 @@ public class PaymentRequired : Error
85
86
}
86
87
```
87
88
88
-
It would therefore make sense to map this to a `402 Payment Required` HTTP response with relevant `ProblemDetails`.
89
+
It would therefore make sense to map this to a `402 Payment Required` HTTP response with relevant `ProblemDetails`.
89
90
This can be achieved like so:
90
91
91
92
```csharp
@@ -105,10 +106,10 @@ public async Task<IActionResult> GetNewsItem(string id)
105
106
}
106
107
```
107
108
108
-
The type field should return a URI that resolves to human-readable documentation about the type of error that has occurred.
109
-
This can either be existing documentation, such as https://httpstatuses.com for common errors, or your own documentation for domain-specific errors.
109
+
The type field should return a URI that resolves to human-readable documentation about the type of error that has occurred.
110
+
This can either be existing documentation, such as [https://httpstatuses.com](https://httpstatuses.com) for common errors, or your own documentation for domain-specific errors.
110
111
111
-
Problem details is formally documented in [RFC 7807](https://tools.ietf.org/html/rfc7807).
112
+
Problem details is formally documented in [RFC 7807](https://tools.ietf.org/html/rfc7807).
112
113
More information about how the fields should be used can be found there.
113
114
114
115
In order to maintain a loose coupling between the API layer and the domain model each action method should know how to map any kind of domain error.
By using C# pattern matching we can easily match on the type of error and map it to a `ProblemDetails`.
139
+
By using C# pattern matching we can easily match on the type of error and map it to a `ProblemDetails`.
139
140
Returning `null` in the default case means the existing error mappings for the common error types, as defined above, are used.
140
141
141
-
If you have a custom error type and you are happy for your REST API to return `400 Bad Request` when it occurs, then the default error mappings for the base `Error` type should already work for you.
142
+
If you have a custom error type and you are happy for your REST API to return `400 Bad Request` when it occurs, then the default error mappings for the base `Error` type should already work for you.
142
143
It maps the error's details and title to the corresponding fields on the problem details.
0 commit comments