Problem Details for ASP.NET Core APIs

Milan Jovanović - Oct 22 - - Dev Community

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 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, which replaces RFC 7807, 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:

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"
}
Enter fullscreen mode Exit fullscreen mode

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.

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();
Enter fullscreen mode Exit fullscreen mode

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

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
}
Enter fullscreen mode Exit fullscreen mode

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

Global Error Handling

We have a few options for implementing global error handling. 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:

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>();
Enter fullscreen mode Exit fullscreen mode

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:

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
        });
    }
}
Enter fullscreen mode Exit fullscreen mode

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).

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);
}
Enter fullscreen mode Exit fullscreen mode

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.

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);
    };
});
Enter fullscreen mode Exit fullscreen mode

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

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"
}
Enter fullscreen mode Exit fullscreen mode

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

Image description

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.

app.UseExceptionHandler(new ExceptionHandlerOptions
{
    StatusCodeSelector = ex => ex switch
    {
        ArgumentException => StatusCodes.Status400BadRequest,
        NotFoundException => StatusCodes.Status404NotFound,
        _ => StatusCodes.Status500InternalServerError
    }
});
Enter fullscreen mode Exit fullscreen mode

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.

Problem Details is just one of the best practices covered in my upcoming RESTful APIs course. Check it out if you're looking for a comprehensive guide.

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

P.S. Whenever you're ready, there are 3 ways I can help you:

  1. Pragmatic Clean Architecture: Join 3,050+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.

  2. Modular Monolith Architecture: Join 1,000+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.

  3. Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Image
10 Reasons Why People Hate Accident Lawyers Firm Accident Lawyers Firm
Image
Halloween Candy Trading Rules with Corticon

nocode, tutorial, corticon, showdev
Image
Entendendo o PROCV: Como Utilizá-lo em Suas Análises de Dados
Image
Internal Developer Portals: Autonomy, Governance and the Golden Path

sre, idp, platformengineering, developers
Image
Stwórz swoją Oazę Spokoju: Inspiracje na Meble do Sypialni
Image
The Time Has Come To Expand Your Asbestos Cancer Claim Options
Image
10 Apps To Help Manage Your Causes Of Mesothelioma Other Than Asbestos
Image
Mai Huong Pham Thi
Image
SAT classes
Image
Will Drip Coffee Brewer Be The Next Supreme Ruler Of The World?
Image
10 Steps To Begin The Business Of Your Dream Coffee Filter Maker Business
Image
Understanding and Using Window Functions in SQL

sql, windowfunction, database, beginners
Image
12 Facts About Repair Bifold Door Bottom Pivot To Make You Look Smart Around The Cooler Water Cooler
Image
Researchers Uncover Python Package Targeting Crypto Wallets with Malicious Code
Image
Mengetahui Sumber Pendapatan Situs Taruhan Judi
Image
🚀 How I Built "News Pulse" with CopilotKit 🚀
Image
15 Up-And-Coming Accident Lawyer Jacksonville Bloggers You Need To Keep An Eye On
Image
A Provocative Rant About Wheelchair Self Propelled
Image
How To Choose The Right Self Propelled Wheelchair With Suspension Online
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Terabox Video Player