
<Sponsorships>

Remember when APIs were an afterthought?
We're [**not going back**](https://shortclick.link/djx5wv).
74% of devs surveyed in the 2024 State of the API Report are API-first, up from 66% in 2023.
What else? We're getting faster. 63% of devs can produce an API within a week, up from 47% in 2023.
Collaboration on APIs is still a challenge.
APIs are increasingly revenue generators.
Read the [**rest of the report**](https://shortclick.link/djx5wv) for fresh insights.

New Report: [**State of Designer-Developer Collaboration 2024**](https://www.telerik.com/design-system/designer-developer-collaboration-survey-2024/?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_survey_design_story_dev_collab_report).
Whether you're on the development or design end of creating web applications, it's easy to lose track of the world beyond your daily work.
This brand-new report will give you some interesting insights and in-depth analysis on the relationship between designers and developers,
including excellent ideas for making it more efficient and satisfying.
[**Check it out**](https://www.telerik.com/design-system/designer-developer-collaboration-survey-2024/?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_survey_design_story_dev_collab_report).

</Sponsorships>

I see the same mistake happen over and over again.

Developers discover Clean Architecture, get excited about its principles, and then... they turn the famous Clean Architecture diagram into a project structure.

But here's the thing: **Clean Architecture is not about folders**.
It's about dependencies.

Simon Brown wrote a "missing chapter" for Uncle Bob's Clean Architecture book that addresses exactly this issue.
Yet somehow, this crucial message got lost along the way.

Today, I'll show you what Uncle Bob's Clean Architecture diagram really means and how you should actually organize your code.
We'll look at practical examples that you can use in your projects right now.

Let's clear up this common misconception once and for all.

## The Problem With Traditional Layering

Almost every .NET developer has built a solution that looks like this:

- `MyApp.Web` for controllers and views
- `MyApp.Business` for services and business logic
- `MyApp.Data` for repositories and data access

It's the default approach. It's what we see in tutorials. It's what we teach juniors.

And it's completely wrong.

### Why Layer-Based Organization Fails

When you organize code by technical layers, you scatter related components across multiple projects.
A single feature, like managing policies, ends up spread across your entire codebase:

- Policies controller in the Web layer
- Policy service in the Business layer
- Policy repository in the Data layer

Here's what you'll see when looking at the folder structure:

```text
📁 MyApp.Web
|__ 📁 Controllers
    |__ #️⃣ PoliciesController.cs
📁 MyApp.Business
|__ 📁 Services
    |__ #️⃣ PolicyService.cs
📁 MyApp.Data
|__ 📁 Repositories
    |__ #️⃣ PolicyRepository.cs
```

Here's a visual representation of the layer-based architecture:

<div className="centered">
  <Image
    src="blogs/mnw_114/layered_architecture.png"
    width={490 * 0.5}
    height={1247 * 0.5}
    alt="Feature Scattering in Layer-Based Architecture."
  />
</div>

This fragmentation creates several problems:

1. **Violates Common Closure Principle** - Classes that change together should stay together.
   When your "Policies" feature changes, you're touching three different projects.

2. **Hidden dependencies** - Public interfaces everywhere make it possible to bypass layers.
   Nothing stops a controller from directly accessing a repository.

3. **No business intent** - Opening your solution tells you nothing about what the application does.
   It only shows technical implementation details.

4. **Harder maintenance** - Making changes requires jumping between multiple projects.

The worst part? This approach doesn't even achieve what it promises.
Despite the separate projects, you often end up with a "big ball of mud" because public access modifiers allow any class to reference any other class.

### The Real Intent of Layers

Clean Architecture's circles were never meant to represent projects or folders.
They represent different levels of policy, with dependencies pointing inward toward business rules.

You can achieve this without splitting your code into artificial technical layers.

Let me show you a better way.

## Better Approaches to Code Organization

Instead of splitting your code by technical layers, you have two better options: **package by feature** or **package by component**.

Let's look at both.

### Package by Feature

Organizing by feature is a solid option.
Each feature gets its own namespace and contains everything needed to implement that feature.

```text
📁 MyApp.Policies
|__ 📁 RenewPolicy
    |__ #️⃣ RenewPolicyCommand.cs
    |__ #️⃣ RenewPolicyHandler.cs
    |__ #️⃣ PolicyValidator.cs
    |__ #️⃣ PolicyRepository.cs
|__ 📁 ViewPolicyHistory
    |__ #️⃣ PolicyHistoryQuery.cs
    |__ #️⃣ PolicyHistoryHandler.cs
    |__ #️⃣ PolicyHistoryViewModel.cs
```

Here's a diagram representing this structure:

<div className="centered">
  <Image
    src="blogs/mnw_114/feature_folder_architecture.png"
    width={490 * 0.5}
    height={1247 * 0.5}
    alt="Vertical slice architecture for package by feature organization."
  />
</div>

This approach:

- Makes features explicit
- Keeps related code together
- Simplifies navigation
- Makes it easier to maintain and modify features

If you want to learn more, check out my article about [**vertical slice architecture**](vertical-slice-architecture).

### Package by Component

A component is a cohesive group of related functionality with a well-defined interface.
Component-based organization is more coarse-grained than feature folders.
Think of it as a mini application that handles one specific business capability.

This is very similar to how I define modules in a [**modular monolith**](what-is-a-modular-monolith).

Here's what a component-based organization looks like:

```text
📁 MyApp.Web
|__ 📁 Controllers
    |__ #️⃣ PoliciesController.cs
📁 MyApp.Policies
|__ #️⃣ PoliciesComponent.cs     // Public interface
|__ #️⃣ PolicyService.cs         // Implementation detail
|__ #️⃣ PolicyRepository.cs      // Implementation detail
```

The key difference? Only `PoliciesComponent` is public.
Everything else is internal to the component.

<div className="centered">
  <Image
    src="blogs/mnw_114/component_architecture.png"
    width={491 * 0.5}
    height={1247 * 0.5}
    alt="Feature Scattering in Layer-Based Architecture."
  />
</div>

This means:

- No bypassing layers
- Clear dependencies
- Real encapsulation
- Business intent visible in the structure

### Which One Should You Choose?

Choose **Package by Feature** when:

- You have many small, independent features
- Your features don't share much code
- You want maximum flexibility

Choose **Package by Component** when:

- You have clear business capabilities
- You want strong encapsulation
- You might split into microservices later

Both approaches achieve what Clean Architecture really wants: proper dependency management and business focus.

Here's a side-by-side comparison of these architectural approaches:

<figure>
  <div className="centered">
    <Image
      src="blogs/mnw_114/architecture_comparison.png"
      width={1934}
      height={1247}
      alt="Comparison between layered, vertical slice and component architectural approaches."
    />
  </div>
  <figcaption>
    Greyed-out types are internal to the defining assembly.
  </figcaption>
</figure>

In the Missing Chapter of Clean Architecture, Simon Brown argues strongly for package by component.
The key insight is that components are the natural way to slice a system.
They represent complete business capabilities, not just technical features.

My recommendation?
Start with package by component.
Within the component, organize around features.

## Practical Examples

Let's transform a typical layered application into a clean, component-based structure.
We'll use an insurance policy system as an example.

### The Traditional Way

Here's how most developers structure their solution:

```csharp
// MyApp.Data
public interface IPolicyRepository
{
    Task<Policy> GetByIdAsync(string policyNumber);
    Task SaveAsync(Policy policy);
}

// MyApp.Business
public class PolicyService : IPolicyService
{
    private readonly IPolicyRepository _repository;

    public PolicyService(IPolicyRepository repository)
    {
        _repository = repository;
    }

    public async Task RenewPolicyAsync(string policyNumber)
    {
        var policy = await _repository.GetByIdAsync(policyNumber);
        // Business logic here
        await _repository.SaveAsync(policy);
    }
}

// MyApp.Web
public class PoliciesController : ControllerBase
{
    private readonly IPolicyService _policyService;

    public PoliciesController(IPolicyService policyService)
    {
        _policyService = policyService;
    }

    [HttpPost("renew/{policyNumber}")]
    public async Task<IActionResult> RenewPolicy(string policyNumber)
    {
        await _policyService.RenewPolicyAsync(policyNumber);
        return Ok();
    }
}
```

The problem?
Everything is public.
Any class can bypass the service and go straight to the repository.

### The Clean Way

Here's the same functionality organized as a proper component:

```csharp
// The only public contract
public interface IPoliciesComponent
{
    Task RenewPolicyAsync(string policyNumber);
}

// Everything below is internal to the component
internal class PoliciesComponent : IPoliciesComponent
{
    private readonly IRenewPolicyHandler _renewPolicyHandler;

    // Public constructor for DI
    public PoliciesComponent(IRenewPolicyHandler renewPolicyHandler)
    {
        _renewPolicyHandler = renewPolicyHandler;
    }

    public async Task RenewPolicyAsync(string policyNumber)
    {
        await _renewPolicyHandler.HandleAsync(policyNumber);
    }
}

internal interface IRenewPolicyHandler
{
    Task HandleAsync(string policyNumber);
}

internal class RenewPolicyHandler : IRenewPolicyHandler
{
    private readonly IPolicyRepository _repository;

    internal RenewPolicyHandler(IPolicyRepository repository)
    {
        _repository = repository;
    }

    public async Task HandleAsync(string policyNumber)
    {
        var policy = await _repository.GetByIdAsync(policyNumber);
        // Business logic for policy renewal here
        await _repository.SaveAsync(policy);
    }
}

internal interface IPolicyRepository
{
    Task<Policy> GetByIdAsync(string policyNumber);
    Task SaveAsync(Policy policy);
}
```

The key improvements are:

1. **Single public interface** - Only `IPoliciesComponent` is public. Everything else is internal.

2. **Protected dependencies** - No way to bypass the component and access the repository directly.

3. **Clear dependencies** - All dependencies flow inward through the component.

4. **Proper encapsulation** - Implementation details are truly hidden.

This is how you would register the services with dependency injection:

```csharp
services.AddScoped<IPoliciesComponent, PoliciesComponent>();
services.AddScoped<IRenewPolicyHandler, RenewPolicyHandler>();
services.AddScoped<IPolicyRepository, SqlPolicyRepository>();
```

This structure enforces Clean Architecture principles through compiler-checked boundaries, not just conventions.

The compiler won't let you bypass the component's public interface.
That's much stronger than hoping developers follow the rules.

## Best Practices and Limitations

Let's discuss something that is often overlooked: the practical limitations of enforcing Clean Architecture in .NET.

### The Limits of Encapsulation

The `internal` keyword in .NET provides protection within a single assembly.
Here's what that means in practice:

```csharp
// In a single project:
public interface IPoliciesComponent { } // Public contract
internal class PoliciesComponent : IPoliciesComponent { }
internal class PolicyRepository { }

// Someone could still do this:
public class BadPoliciesComponent : IPoliciesComponent
{
    public BadPoliciesComponent()
    {
        // Nothing stops them from creating a bad implementation
    }
}
```

While `internal` helps, it doesn't prevent all architectural violations.

### The Trade-offs

Some teams split their code into separate assemblies for stronger encapsulation:

```plaintext
MyCompany.Policies.Core.dll
MyCompany.Policies.Infrastructure.dll
MyCompany.Policies.Api.dll
```

This comes with trade-offs:

1. **More complex build process** - Multiple projects need to be compiled and referenced.
2. **Harder navigation** - Jumping between assemblies in the IDE is slower.
3. **Deployment complexity** - More DLLs to manage and deploy.

### A Pragmatic Approach

Here's what I recommend:

1. **Use a single assembly**

   - Keep related code together
   - Use `internal` for implementation details
   - Make only the component interfaces public
   - Add `sealed` to prevent inheritance when possible

2. **Enforce through architecture testing**

   - Add architecture tests to verify dependencies
   - Automatically check for architectural violations
   - Fail the build if someone bypasses the rules

```csharp
[Fact]
public void Controllers_Should_Only_Depend_On_Component_Interfaces()
{
    var result = Types.InAssembly(Assembly.GetExecutingAssembly())
        .That()
        .ResideInNamespace("MyApp.Controllers")
        .Should()
        .OnlyDependOn(type =>
            type.Name.EndsWith("Component") ||
            type.Name.StartsWith("IPolicy"))
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}
```

Want to learn more about enforcing architecture through testing?
Check out my article on [**architecture testing**](enforcing-software-architecture-with-architecture-tests).

Remember: Clean Architecture is about managing dependencies, not about achieving perfect encapsulation.
Use the tools the language gives you, but don't over-complicate things chasing an impossible ideal.

## Conclusion

Clean Architecture isn't about projects, folders, or perfect encapsulation.

It's about:

- Organizing code around business capabilities
- Managing dependencies effectively
- Keeping related code together
- Making boundaries explicit

Start with a single project.
Use components.
Make interfaces public and implementations internal.
Add architecture tests if you need more control.

And remember: **pragmatism beats purism**.
Your architecture should help you ship features faster, not slow you down with artificial constraints.

Want to learn more?
Check out my [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) course,
where I'll show you how to build maintainable applications with proper boundaries, clear dependencies, and business-focused components.

That's all for today. Stay awesome, and I'll see you next week.

---



<Sponsorships>

Looking for a developer-friendly, affordable eSignature solution?
[**BoldSign**](https://boldsign.com/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign) offers highly responsive and secure API integration for your .NET applications with transparent pricing—making it the perfect
[**alternative to DocuSign**](https://boldsign.com/docusign-alternative/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign).
Start your free trial today.

Transform your team's API development.
See how [**Postman Flows**](https://app.zuddl.com/p/a/event/b718e16b-9456-4da3-9af1-f990b252ceb5?utm_source=influencer&utm_medium=Newsletter&utm_campaign=Flows_collab&utm_term=Milan_Jovanovic&utm_content=Webinar)
eliminates bottlenecks & enables seamless collaboration.
Join the finale of our "Visualize, Accelerate, & Collaborate" series to supercharge your workflow.
[**Register now**](https://app.zuddl.com/p/a/event/b718e16b-9456-4da3-9af1-f990b252ceb5?utm_source=influencer&utm_medium=Newsletter&utm_campaign=Flows_collab&utm_term=Milan_Jovanovic&utm_content=Webinar).

</Sponsorships>

Idempotency is a crucial concept for REST APIs that ensures the reliability and consistency of your system.
An idempotent operation can be repeated multiple times without changing the result beyond the initial API request.
This property is especially important in distributed systems, where network failures or timeouts can lead to repeated requests.

Implementing idempotency in your API brings several benefits:

- It prevents unintended duplicate operations
- It improves reliability in distributed systems
- It helps handle network issues and retries gracefully

In this week's issue, we'll explore how to implement idempotency in ASP.NET Core APIs, ensuring your system remains robust and reliable.

## What is Idempotence?

Idempotence, in the context of web APIs, means that making multiple identical requests should have the same effect as making a single request.
In other words, no matter how many times a client sends the same request, the server-side effect should only occur once.

The [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) standard about HTTP Semantics offers a definition we could use.
Here's what it says about **idempotent methods**:

<figure>

> A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with
> that method is the same as the effect for a single such request.
>
> Of the request methods defined by this specification,
> PUT, DELETE, and safe request methods [(GET, HEAD, OPTIONS, and TRACE) - author's note] are idempotent.

  <figcaption>
    _&mdash; [RFC 9110 (HTTP Semantics), Section 9.2.2, Paragraph 1](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.2-1)_
  </figcaption>
</figure>

However, the following paragraph is quite interesting.
It clarifies that the server can implement "other non-idempotent side effects" that don't apply to the resource.

<figure>

> ... the idempotent property only applies to what has been requested by the user;
> a server is free to log each request separately, retain a revision control history, or implement other non-idempotent side effects for each idempotent request.

  <figcaption>
    _&mdash; [RFC 9110 (HTTP Semantics), Section 9.2.2, Paragraph 2](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.2-2)_
  </figcaption>
</figure>

The benefits of implementing idempotency extend beyond just adhering to HTTP method semantics.
It significantly improves the reliability of your API, especially in distributed systems where network issues can lead to retried requests.
By implementing idempotency, you prevent duplicate operations that could occur due to client retries.

## Which HTTP Methods are Idempotent?

Several HTTP methods are inherently idempotent:

- `GET`, `HEAD`: Retrieve data without modifying the server state.
- `PUT`: Update a resource, resulting in the same state regardless of repetition.
- `DELETE`: Remove a resource with the same outcome for multiple requests.
- `OPTIONS`: Retrieve communication options information.

`POST` is not inherently idempotent, as it typically creates resources or processes data.
Repeated `POST` requests could create multiple resources or trigger multiple actions.

However, we can implement idempotency for `POST` methods using custom logic.

**Note**: While `POST` requests aren't naturally idempotent, we can design them to be.
For example, checking for existing resources before creation ensures that repeated `POST` requests don't result in duplicate actions or resources.

## Implementing Idempotency in ASP.NET Core

To implement idempotency, we'll use a strategy involving idempotency keys:

1. The client generates a unique key for each operation and sends it in a custom header.
2. The server checks if it has seen this key before:
   - For a new key, process the request and store the result.
   - For a known key, return the stored result without reprocessing.

This ensures that retried requests (e.g., due to network issues) are processed only once on the server.

We can implement idempotency for controllers by combining an `Attribute` and `IAsyncActionFilter`.
Now, we can specify the `IdempotentAttribute` to apply idempotency to a controller endpoint.

**Note**: When a request fails (returns 4xx/5xx), we don't cache the response.
This allows clients to retry with the same idempotency key.
However, this means a failed request followed by a successful one with the same key will succeed - make sure this aligns with your business requirements.

```csharp
[AttributeUsage(AttributeTargets.Method)]
internal sealed class IdempotentAttribute : Attribute, IAsyncActionFilter
{
    private const int DefaultCacheTimeInMinutes = 60;
    private readonly TimeSpan _cacheDuration;

    public IdempotentAttribute(int cacheTimeInMinutes = DefaultCacheTimeInMinutes)
    {
        _cacheDuration = TimeSpan.FromMinutes(minutes);
    }

    public async Task OnActionExecutionAsync(
        ActionExecutingContext context,
        ActionExecutionDelegate next)
    {
        // Parse the Idempotence-Key header from the request
        if (!context.HttpContext.Request.Headers.TryGetValue(
                "Idempotence-Key",
                out StringValues idempotenceKeyValue) ||
            !Guid.TryParse(idempotenceKeyValue, out Guid idempotenceKey))
        {
            context.Result = new BadRequestObjectResult("Invalid or missing Idempotence-Key header");
            return;
        }

        IDistributedCache cache = context.HttpContext
            .RequestServices.GetRequiredService<IDistributedCache>();

        // Check if we already processed this request and return a cached response (if it exists)
        string cacheKey = $"Idempotent_{idempotenceKey}";
        string? cachedResult = await cache.GetStringAsync(cacheKey);
        if (cachedResult is not null)
        {
            IdempotentResponse response = JsonSerializer.Deserialize<IdempotentResponse>(cachedResult)!;

            var result = new ObjectResult(response.Value) { StatusCode = response.StatusCode };
            context.Result = result;

            return;
        }

        // Execute the request and cache the response for the specified duration
        ActionExecutedContext executedContext = await next();

        if (executedContext.Result is ObjectResult { StatusCode: >= 200 and < 300 } objectResult)
        {
            int statusCode = objectResult.StatusCode ?? StatusCodes.Status200OK;
            IdempotentResponse response = new(statusCode, objectResult.Value);

            await cache.SetStringAsync(
                cacheKey,
                JsonSerializer.Serialize(response),
                new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = _cacheDuration }
            );
        }
    }
}

internal sealed class IdempotentResponse
{
    [JsonConstructor]
    public IdempotentResponse(int statusCode, object? value)
    {
        StatusCode = statusCode;
        Value = value;
    }

    public int StatusCode { get; }
    public object? Value { get; }
}
```

**Note**: There's a small [**race condition**](solving-race-conditions-with-ef-core-optimistic-locking) window between checking and setting the cache.
For absolute consistency, we should consider using a distributed lock pattern, though this adds complexity and latency.

Now, we can apply this attribute to our controller actions:

```csharp {6}
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpPost]
    [Idempotent(cacheTimeInMinutes: 60)]
    public IActionResult CreateOrder([FromBody] CreateOrderRequest request)
    {
        // Process the order...

        return CreatedAtAction(nameof(GetOrder), new { id = orderDto.Id }, orderDto);
    }
}
```

**Idempotency with Minimal APIs**

To implement idempotency with Minimal APIs, we can use an `IEndpointFilter`.

```csharp
internal sealed class IdempotencyFilter(int cacheTimeInMinutes = 60)
    : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        // Parse the Idempotence-Key header from the request
        if (TryGetIdempotenceKey(out Guid idempotenceKey))
        {
            return Results.BadRequest("Invalid or missing Idempotence-Key header");
        }

        IDistributedCache cache = context.HttpContext
            .RequestServices.GetRequiredService<IDistributedCache>();

        // Check if we already processed this request and return a cached response (if it exists)
        string cacheKey = $"Idempotent_{idempotenceKey}";
        string? cachedResult = await cache.GetStringAsync(cacheKey);
        if (cachedResult is not null)
        {
            IdempotentResponse response = JsonSerializer.Deserialize<IdempotentResponse>(cachedResult)!;
            return new IdempotentResult(response.StatusCode, response.Value);
        }

        object? result = await next(context);

        // Execute the request and cache the response for the specified duration
        if (result is IStatusCodeHttpResult { StatusCode: >= 200 and < 300 } statusCodeResult
            and IValueHttpResult valueResult)
        {
            int statusCode = statusCodeResult.StatusCode ?? StatusCodes.Status200OK;
            IdempotentResponse response = new(statusCode, valueResult.Value);

            await cache.SetStringAsync(
                cacheKey,
                JsonSerializer.Serialize(response),
                new DistributedCacheEntryOptions
                {
                    AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(cacheTimeInMinutes)
                }
            );
        }

        return result;
    }
}

// We have to implement a custom result to write the status code
internal sealed class IdempotentResult : IResult
{
    private readonly int _statusCode;
    private readonly object? _value;

    public IdempotentResult(int statusCode, object? value)
    {
        _statusCode = statusCode;
        _value = value;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.StatusCode = _statusCode;

        return httpContext.Response.WriteAsJsonAsync(_value);
    }
}
```

Now, we can apply this endpoint filter to our Minimal API endpoint:

```csharp {4}
app.MapPost("/api/orders", CreateOrder)
    .RequireAuthorization()
    .WithOpenApi()
    .AddEndpointFilter<IdempotencyFilter>();
```

An alternative to the previous two implementations is implementing idempotency logic in a custom middleware.

## Best Practices and Considerations

Here are the key things I always keep in mind when implementing idempotency.

Cache duration is tricky.
I aim to cover reasonable retry windows without holding onto stale data.
A reasonable cache time typically ranges from a few minutes to 24-48 hours, depending on your specific use case.

Concurrency can be a pain, especially in high-traffic APIs.
A thread-safe implementation using a distributed lock works great.
It keeps things in check when multiple requests hit at once.
But this should be a rare occurrence.

For distributed setups, Redis is my go-to.
It's perfect as a shared cache, keeping idempotency consistent across all your API instances.
Plus, it handles distributed locking.

What if a client reuses an idempotency key with a different request body?
I return an error in this case.
My approach is to hash the request body and store it with the idempotency key.
When a request comes in, I compare the request body hashes.
If they differ, I return an error.
This prevents misuse of idempotency keys and maintains the integrity of your API.

## Summary

Implementing idempotency in REST APIs enhances service reliability and consistency.
It ensures identical requests yield the same result, preventing unintended duplicates and gracefully handling network issues.

While our implementation provides a foundation, I recommend adapting it to your needs.
Focus on critical operations in your APIs, especially those that modify the system state or trigger important business processes.

By embracing idempotency, you're building more robust and user-friendly APIs.

That's all for today.

See you next week.

---



<Sponsorships>

[**Telerik UI for ASP.NET Core Grid**](https://www.telerik.com/blogs/editing-data-telerik-ui-aspnet-core-grid-no-code-required?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=core-general-awareness):
Enable data editing without code.
Multiple options for customizing user experience.
Configure the grid easily to meet your UX needs.
[**Learn more here**](https://www.telerik.com/blogs/editing-data-telerik-ui-aspnet-core-grid-no-code-required?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=core-general-awareness).

Webinar: [**Accelerating with AI using Postman Flows**](https://app.zuddl.com/p/a/event/aa49e0b7-9b7b-43d2-afce-282fcf08a756?utm_source=influencer&utm_medium=Newsletter&utm_campaign=Flows_AI&utm_term=Milan_Jovanovic&utm_content=Webinar).
Second in our series on visualizing, accelerating, and collaborating with Postman Flows.
Learn how AI enhances API development and speeds up your workflow.
[**Register here for free**](https://app.zuddl.com/p/a/event/aa49e0b7-9b7b-43d2-afce-282fcf08a756?utm_source=influencer&utm_medium=Newsletter&utm_campaign=Flows_AI&utm_term=Milan_Jovanovic&utm_content=Webinar).

</Sponsorships>

When developing HTTP APIs, providing consistent and informative error responses is crucial for a smooth developer experience.
**Problem Details** in ASP.NET Core offers a standardized solution to this challenge, ensuring your APIs communicate errors effectively and uniformly.

In this article, we'll explore the latest developments in **Problem Details**, including:

- The new [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) that refines the Problem Details standard
- Using the .NET 8 `IExceptionHandler` for global exception handling
- Using the `IProblemDetailsService` for customizing Problem Details

Let's dive into these features and see how they can improve your API's error handling.

## Understanding Problem Details

Problem Details is a machine-readable format for specifying errors in HTTP API responses.
HTTP status codes don't always contain enough details about errors to be helpful.
The Problem Details specification defines a JSON (and XML) document format to describe problems.

Problem Details includes:

- `type`: A URI reference that identifies the problem type
- `title`: A short, human-readable summary of the problem type
- `status`: The HTTP status code
- `detail`: A human-readable explanation specific to this occurrence of the problem
- `instance`: A URI reference that identifies the specific occurrence of the problem

[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), which replaces [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807),
introduces improvements such as clarifying the use of the type field and providing guidelines for extending **Problem Details**.

Here's an example Problem Details response:

```json
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "The habit with the specified identifier was not found",
  "instance": "PUT /api/habits/aadcad3f-8dc8-443d-be44-3d99893ba18a"
}
```

## Implementing Problem Details

Let's see how to implement Problem Details in ASP.NET Core.
We want to return a Problem Details response for unhandled exceptions.
By calling `AddProblemDetails`, we're configuring the application to use the Problem Details format for failed requests.
With `UseExceptionHandler`, we introduce an exception handling middleware to the request pipeline.
By adding `UseStatusCodePages`, we're introducing a middleware that will convert error responses with an empty body to a Problem Details response.

```csharp {4,9,12}
var builder = WebApplication.CreateBuilder(args);

// Adds services for using Problem Details format
builder.Services.AddProblemDetails();

var app = builder.Build();

// Converts unhandled exceptions into Problem Details responses
app.UseExceptionHandler();

// Returns the Problem Details response for (empty) non-successful responses
app.UseStatusCodePages();

app.Run();
```

When we encounter an unhandled exception, it will be translated to a Problem Details response:

```json
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500
}
```

Now, let's explore how we can customize this response.

## Global Error Handling

We have a few options for [implementing global error handling](global-error-handling-in-aspnetcore-8).
The most popular approach is creating a custom exception handling middleware.
You wrap the API request in a `try-catch` statement and return a response based on any caught exception.

With .NET 8, we can use the `IExceptionHandler` that runs in the built-in exception handling middleware.
This handler allows you to tailor the Problem Details response for specific exceptions.
Returning `true` from the `TryHandleAsync` method short-circuits the pipeline and returns the API response.
If we return `false`, the next handler in the chain attempts to handle the exception.

We can map different exception types to appropriate HTTP status codes, providing more precise error information to API consumers.

Here's an example `CustomExceptionHandler` implementation:

```csharp
internal sealed class CustomExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        int status = exception switch
        {
            ArgumentException => StatusCodes.Status400BadRequest,
            _ => StatusCodes.Status500InternalServerError
        };
        httpContext.Response.StatusCode = status;

        var problemDetails = new ProblemDetails
        {
            Status = status,
            Title = "An error occurred",
            Type = exception.GetType().Name,
            Detail = exception.Message
        };

        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;
    }
}

// In Program.cs
builder.Services.AddExceptionHandler<CustomExceptionHandler>();
```

## Using The ProblemDetailsService

Calling `AddProblemDetails` registers a default implementation of the `IProblemDetailsService`.
The `IProblemDetailsService` will set the response status code based on the `ProblemDetails.Status`.

Here's how we can use it in the `CustomExceptionHandler`:

```csharp
public class CustomExceptionHandler(IProblemDetailsService problemDetailsService) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var problemDetails = new ProblemDetails
        {
            Status = exception switch
            {
                ArgumentException => StatusCodes.Status400BadRequest,
                _ => StatusCodes.Status500InternalServerError
            },
            Title = "An error occurred",
            Type = exception.GetType().Name,
            Detail = exception.Message
        };

        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            Exception = exception,
            HttpContext = httpContext,
            ProblemDetails = problemDetails
        });
    }
}
```

This approach seems very similar to the previous one, where we wrote to the response body.
However, using the `IProblemDetailsService` gives an easy way to customize all Problem Details responses.

We can return Problem Details in controllers using the `Problem` method, or `Results.Problem` in Minimal APIs.
These methods respect the configured Problem Details customizations (more on this in the next section).

```csharp
IdentityUser identityUser = new() { UserName = registerUserDto.UserName, Email = registerUserDto.Email };
IdentityResult result = await userManager.CreateAsync(identityUser, registerUserDto.Password);

if (!result.Succeeded)
{
    // return Results.Problem - Minimal APIs
    return Problem(
        type: "Bad Request",
        title: "Identity failure",
        detail: result.Errors.First().Description,
        statusCode: StatusCodes.Status400BadRequest);
}
```

## Customizing Problem Details

We can pass a delegate to the `AddProblemDetails` method to set the `CustomizeProblemDetails`.
You can use this to add extra information to all Problem Details responses.

This is an excellent place for solving cross-cutting concerns, like setting the `instance` value and adding diagnostics information.

```csharp
builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        context.ProblemDetails.Instance =
            $"{context.HttpContext.Request.Method} {context.HttpContext.Request.Path}";

        context.ProblemDetails.Extensions.TryAdd("requestId", context.HttpContext.TraceIdentifier);

        Activity? activity = context.HttpContext.Features.Get<IHttpActivityFeature>()?.Activity;
        context.ProblemDetails.Extensions.TryAdd("traceId", activity?.Id);
    };
});
```

This customization adds the request path, a request ID, and a trace ID to every Problem Details response, enhancing debuggability and traceability of errors.

```json {7-9}
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "instance": "PUT /api/habits/aadcad3f-8dc8-443d-be44-3d99893ba18a",
  "traceId": "00-63d4af1807586b0d98901ae47944192d-9a8635facb90bf76-01",
  "requestId": "0HN7C8PRNMGIA:00000001"
}
```

You can use the `traceId` to find the distributed traces and logs in a monitoring system like Seq.

<div className="bordered">
  <Image
    src="blogs/mnw_112/seq_tracing.png"
    width={1919}
    height={905}
    alt="Seq user interface showing a distributed trace with the same trace identifier as the problem details response."
  />
</div>

## Handling Specific Exceptions (Status Codes)

.NET 9 introduces a simpler way to map exceptions to status codes.
Great news for fans of throwing exceptions.
You can use the `StatusCodeSelector` to define the mappings.
This makes it easier to maintain consistent error responses across your API.

```csharp
app.UseExceptionHandler(new ExceptionHandlerOptions
{
    StatusCodeSelector = ex => ex switch
    {
        ArgumentException => StatusCodes.Status400BadRequest,
        NotFoundException => StatusCodes.Status404NotFound,
        _ => StatusCodes.Status500InternalServerError
    }
});
```

If you use this together with an `IExceptionHandler` that sets the `StatusCode`, then the `StatusCodeSelector` is ignored.

## Takeaway

Implementing Problem Details in your ASP.NET Core APIs is more than just a best practice -
it's a standard for improving the developer experience of your API consumers.
By providing consistent, detailed, and well-structured error responses, you make it easier for clients to understand and handle error scenarios gracefully.

As you implement these practices in your own projects, you'll discover even more ways to tailor Problem Details to your specific needs.
I shared what worked well for my use cases.

{/* Update this when the course is out */}
Problem Details is just one of the best practices covered in my upcoming [**REST APIs course**](/rest-apis-in-aspnetcore).
Check it out if you're looking for a comprehensive guide.

Good luck out there, and I'll see you next week.

---


Latest On YouTube

Let's connect

The .NET Weekly

Latest On YouTube

Let's connect