API Proposal for IApiEndpointMetadata

[halter73]

Background and Motivation

This proposal introduces IApiEndpointMetadata as a new public API in ASP.NET Core. The goal is to provide a standardized metadata interface for identifying API endpoints. The primary use case is to avoid cookie login redirects for known API endpoints as described in #9039.

There is already a PR open for this at #62816

This metadata is automatically applied to endpoints in several scenarios:

• Endpoints using RDF/RDG that read a JSON request body or write a JSON response body.
• Endpoints attributed with ApiController.
• SignalR endpoints.
• Endpoints with TypedResults return types that are recognized as API-oriented.

This change aims to improve discoverability and handling of API endpoints in ASP.NET Core, particularly for scenarios like avoiding cookie login redirects for APIs.

Proposed API

namespace Microsoft.AspNetCore.Http;

+ public interface IApiEndpointMetadata
+ {
+ }

No new attributes or extension methods are introduced in this PR, but the IApiEndpointMetadata interface is automatically assigned to qualifying endpoints.

Usage Examples

// Example: Checking for API endpoint metadata in middleware
public class ApiEndpointMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        var endpoint = context.GetEndpoint();
        if (endpoint?.Metadata.GetMetadata<IApiEndpointMetadata>() != null)
        {
            // This is an API endpoint, apply API-specific logic
        }
        await next(context);
    }
}

// Example: Custom endpoint definition
app.MapPost("/api/data", (MyData data) =>
{
    // This endpoint will automatically get IApiEndpointMetadata
    return TypedResults.Json(data);
});

Alternative Designs

• We could pick a different name like IApiMetadata. Most other Endpoint.Metadata types end in just "Metadata". Or we can invert the logic and instead indicate that the endpoint is targeted at anything other than direct browser navigation.

namespace Microsoft.AspNetCore.Http;

+ public interface IApiMetadata
// or
+ public interface INonBrowserNavigableMetadata
+ {
+ }

• Alternative approaches considered include using attributes or extension methods to mark API endpoints, but the chosen design leverages automatic assignment based on endpoint characteristics.
• Compared to other ecosystems, this is similar to how frameworks like Spring Boot or Express.js identify API routes via metadata or decorators.

Risks

• Automatic assignment of metadata may result in unexpected behavior if endpoints are misclassified.
• There is a minimal risk of breaking changes for existing middleware or components that inspect endpoint metadata.
• Potential performance impact due to additional metadata checks, though expected to be negligible.

[dotnet-policy-service]

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.

[mitchdenny]

@halter73 can this be closed?