Enable Option to Use Content Negotiation for ProblemDetails

[commonsensesoftware]

Background and Motivation

The implementation of DefaultProblemDetailsWriter strictly enforces that ProblemDetails are only written if Accept is present and can be content negotiated. This is contrary to the HTTP specification. RFC 7231 §5.3.2 semantics for the Accept header states:

...disregard the header field by treating the response as if it is not subject to content negotiation.

The current behavior is very sensible as a default. It requires a client to understand they can get a ProblemDetails response; however, it is very common for API authors to not honor content negotiation for errors.

DefaultProblemDetailsWriter is internal and sealed with functionality that cannot be easily extended or customized. Ultimately, an API author simply wants to decide if content negotiation should take place for ProblemDetails and that shouldn't require customization when trivial configuration will suffice.

Proposed API

The proposed API would be to extend ProblemDetailsOptions to include a property to determine whether content negotiation should be used. The default value will be true, which retains the current behavior. If a developer sets the value to false, the expectation is that content negotiation is skipped.

public class ProblemDetailsOptions
{
    /// <summary>
    /// The operation that customizes the current <see cref="Mvc.ProblemDetails"/> instance.
    /// </summary>
    public Action<ProblemDetailsContext>? CustomizeProblemDetails { get; set; }

+   /// <summary>
+   /// Gets or sets a value indicating whether to use HTTP content negotiation.
+   /// </summary>
+   /// <value>True if the content negotiation is used; otherwise, false. The default value is <c>true</c>.</value>
+   public bool UseContentNegotiation { get; set; } = true;
}

Usage Examples

The default configuration where content negotiation is used. This is the same behavior as today.

builder.Services.AddProblemDetails();

A new configuration option which can instruct IProblemDetailsWriter implementations not to honor content negotiation.

builder.Services.AddProblemDetails(options => options.UseContentNegotiation = false);

Risks

Nothing apparent. The default configuration and behavior would be retained.

Additional Information

In accordance with RFC 7231 §5.3.2, if Accept is unspecified or is empty, then the value of ProblemDetailsOptions.UseContentNegotiation should be ignored and implied to be false. This behavior is being tracked in #45051.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

API Review Notes

1. Where is this options used? When writing problem details via the new service for MVC, the error handler middleware, status page result, the developer exception page.
2. Is there another name for UseContentNegotiation that can default for false? IgnoreAcceptHeader?
3. Can we change the default and make a breaking change announcement? The developer exception page will try to render to HTML first, so it shouldn't break that. @commonsensesoftware Do you think it would be too breaking to change the default here?

We'll hold off on approving this until we're confident what we want the default to be. Ideally, we'll have whatever we name the option false by default.

[commonsensesoftware]

Great questions.

1. Where is this option used?

This should be useful in any scenario where ProblemDetails or ProblemDetailsOptions would be used to make a decision, which includes all of the scenarios you outlined.

I was specifically thinking in DefaultProblemDetailsWriter like this:

public DefaultProblemDetailsWriter(IOptions<ProblemDetailsOptions> options)
{
    _options = options.Value;
}

public bool CanWrite(ProblemDetailsContext context)
{
+    if (_options.SkipContentNegotiation)
+    {
+        // always return true because we aren't honoring Accept
+        return true;
+    }
...
}

However, this could just as easily be used for the ProblemDetailsFactory too.

2. Is there another name that can default to false?

• SkipContentNegotiation
• DisableContentNegotation

were a few other variants I considered. Those can be used to default to false.

I did consider IgnoreAcceptHeader, but content negotiation can be more complex that just the Accept header. I was concerned the term would be misleading, even though the alternative is a bit verbose.

Consider the following request:

POST /order HTTP/3
Host: localhost
Content-Type: application/json
Content-Length: 420

{"customer": "John Doe", "product": "Contoso soap", "quantity": 42}

If this results in a client error, say validation, and ProblemDetails were to be returned, then the current behavior would not yield a body because there is no Accept. A server could rationalize that application/problem+json is a reasonable choice because Content-Type was application/json. This would be a form of content negotiation without Accept.

UseContentNegotiation or SkipContentNegotiation would express the same intent, albeit a bit longer, but without restricting it specifically to the Accept header. I have a mild concern that if the option is too specific, then it could lead to additional options or changes in the future. I don't think we'd want to add IgnoreAcceptHeader and then potentially IgnoreContenTypeHeader later.

I'm open to other names, but that's my 2¢.

3. Can we change the default and make a breaking change announcement?

Arguably, the behavior is already broken in .NET 7; at least, using the IProblemDetailsService. I agree and think the behavior to restrict matching a ProblemDetails response to Accept (when specified) is correct, but it was unexpected. I don't immediately see a need to change the default behavior for AddProblemDetails in .NET 8.0+. Anyone that adapts to the .NET 7.0 behavior will likely be upset if things flip-flop. This new option would be congruent with how things currently behave.

As you point out, this option could be used in other places and could be tricky with the current, expected behaviors. Another alternative could be to use:

public bool? SkipContentNegotiation { get; set; }

This would be expected to have the following behaviors:

• false - do not skip content negotiation
• true - skip/ignore content negotiation
• null - the default; since it is unspecified, the option consumer decides which would allow retaining backward compatibility

An enumeration might be more intention revealing here:

public enum ProblemDetailsContentNegotiation
{
    Default = 0, // whatever the existing, default behavior is; backward compatible
    Strict  = 1, // could also be Required, Enforce
    Skip    = 2, // could also be None, Optional
}

public ProblemDetailsContentNegotiation ContentNegotiation { get; set; }