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
Here’s a brief guide on creating a virtual machine using the Azure portal: Creating a Virtual Machine in Azure Portal

beginners, tutorial, devops, learning
Image
Casino Hold'em Gives Texas Holdem Poker Something Feel About
Image
Project 3:Nintendo Division. Tetris Game

tetris, nintendodivision, java, github
Image
Top 8 Tips For Restful API Design
Image
5 Laws Everybody In Crypto Casino Usa Should Be Aware Of
Image
Ansible Ad-Hoc Commands: Quick and Powerful Automation

labex, ansible, coding, programming
Image
Self-healing Strategies For A Happier, More Healthy Thoughts
Image
Wisdom On Crypto Casino Us From An Older Five-Year-Old
Image
Asbestos Mesothelioma Lung Cancer Is The Next Hot Thing In Asbestos Mesothelioma Lung Cancer
Image
Clear illustration of how API Token Authentication works

laravel, php, api, authentication
Image
14 Cartoons On Asbestos Claims Law Which Will Brighten Your Day
Image
11 Ways To Fully Redesign Your Mesothelioma Asbestos Claims
Image
code-server by coder

vscode
Image
Surah Al-Ikhlas "The Purity"
Image
How to get a verified Cash App account?

webdev, javascript, beginners, programming
Image
The Largest Issue That Comes With Exposure Asbestos, And How You Can Repair It
Image
Do You Know How To Explain Autowatch Ghost Installer To Your Mom
Image
55 Famous Inspirational Poems Everybody Should Know
Image
Motivational Words: Speeches, Poems & Quotes That Encourage
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .