Custom Endpoints and Endpoint Metadata Standards?

[nquandt]

I've been searching for a few days for guides as to implementing my own Endpoints via an EndpointDataSource implementation. Where I'm struggling the most is finding information on which metadata objects are used for Authorization/Authentication, HttpMethods, Host, etc. As well as there is seemingly only the source code for YARP and this blog to go off of for seeing how to implement EndpointDataSource.

I can see them used in YARP:
EndpointDataSource

Metadata Add

But am wondering if there are any plans to more formally document how someone might go about creating an endpoint implementation.

I understand that in the following example I would miss out on any "minimal api" specific functionality but believe I should be able to augment this RouteEndpoint, (or a custom Endpoint and Matcher? / IRouter?) to plug into other middleware functionality like Auth.

using Microsoft.AspNetCore.Routing.Patterns;


var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Step 1: Create a RequestDelegate (handler)
RequestDelegate handler = async (HttpContext context) =>
{
    await context.Response.WriteAsync("Hello from custom RouteEndpoint!");
};

// Step 2: Create a RouteEndpoint manually
var routeEndpoint = new RouteEndpoint(
    requestDelegate: handler,
    routePattern: RoutePatternFactory.Parse("/"),
    order: 0,
    metadata: new EndpointMetadataCollection(),
    displayName: "Custom RouteEndpoint"
);

// Step 3: Create an EndpointDataSource that holds custom endpoints
var dataSource = new DefaultEndpointDataSource(routeEndpoint); // could create a custom one of these

// Step 4: Register middleware to use custom endpoint resolution
app.UseRouting();

((IEndpointRouteBuilder)app).DataSources.Add(dataSource);

// Step 5: Start the app
app.Run();

Mostly I'm looking for:

How can I know when to do this and with what classes/instances?

if (hosts is not null && hosts.Count != 0)
{
    endpointBuilder.Metadata.Add(new HostAttribute(hosts.ToArray()));
}

Are there any plans to break out the Metadata.Add calls into ConventionBuilders for each concern? So that someone building a library could call

endpointBuilder.ApplyHostsMetadata(hosts);

My goal: register endpoints based on a custom spec. similar to YARP.
My concern: I use yarp's code as a guide but wont be able to know if the Metadata objects ever have breaking changes.
My hope: Explicit docs, guides, or public API's that guide a developer to success by default.

I am willing to collaborate/contribute as I can. If there were any guidance on this I'd be happy to pick it up to build a proposal but I'm starting somewhat in the dark based on all information I could find.

Any discussion is welcome. Thanks