Advanced HTTP Handlers

public override Task ConfigureHandler(IHttpHandlerConfiguration handlerConfiguration, MyAdvancedHttpHandlerConfig config)
{
    handlerConfiguration.MapGet("/hello-world", () => "Hello World!");
    return Task.CompletedTask;
}

handlerConfiguration.MapGet("/get-custom-response", async (HttpContext httpContext) =>
{
    httpContext.Response.StatusCode = 200;
    httpContext.Response.ContentType = "text/plain";
    await httpContext.Response.WriteAsync("This is a custom response");

    // This response will be ignored, since we have already written the response directly to the HttpContext.Response object,
    // and returning a value from the handler function is not necessary in this case.
    return new { text = "Please ignore me" };
}); 

// Map the most simple get endpoint without parameters or documentation
// This returns a simple anonymous object with a test property, which will be serialized to JSON by default
handlerConfiguration.MapGet("/simple", () => new { test = "Test result" });


// Map an async endpoint to demonstrate that async handlers are supported as well
handlerConfiguration.MapGet("/simple-async", async () => 
{
    await Task.CompletedTask;
    return new { test = "Test result" };
});


// Map an endpoint with a route parameter and demonstrate that it can be used in the handler function
handlerConfiguration.MapGet("/routing/{arg}", ([RouteParam] string arg) => new { test = arg });


// Map an endpoint with a route parameter that has a different name than the parameter in the handler function, and demonstrate how to use the RouteParam attribute to bind them together
handlerConfiguration.MapGet("/routing2/{route-arg}", ([RouteParam(Name = "route-arg")] string arg) => new { test = arg });


// Map an endpoint with a body parameter and demonstrate that it can be used in the handler function
handlerConfiguration.MapPost("/map-body", ([BodyParam] MyRequestObject req) => new { test = $"Hello {req.name}" });


// Map an endpoint with a query parameter and demonstrate that it can be used in the handler function
// This parameter is required by default, so if you try to call this endpoint without providing the 'q' query parameter, it will return a 400 Bad Request response
handlerConfiguration.MapGet("/map-query", ([QueryParam] string q) => new { test = $"q: {q}" });


// Map an endpoint with an optional query parameter by setting IsRequired to false, and demonstrate that the handler function can handle the case when the parameter is not provided (it will be null in that case)
handlerConfiguration.MapGet("/map-query2", ([QueryParam(IsRequired = false)] string q) => new { test = $"q: {q}" });


// Map an endpoint with a body parameter that has a different name than the parameter in the handler function, and demonstrate how to use the BodyParam attribute to bind them together
handlerConfiguration.MapGet("/map-query3", ([QueryParam(Name = "query-param", IsRequired = false)] string q) => new { test = $"query-param: {q}" });


// Map an endpoint with a header parameter and demonstrate that it can be used in the handler function
// This parameter is required by default, so if you try to call this endpoint without providing the 'h' header, it will return a 400 Bad Request response
handlerConfiguration.MapGet("/map-header", ([HeaderParam] string h) => new { test = $"h: {h}" });


// Map an endpoint with an optional header parameter by setting IsRequired to false, and demonstrate that the handler function can handle the case when the parameter is not provided (it will be null in that case)
handlerConfiguration.MapGet("/map-header2", ([HeaderParam(IsRequired = false)] string h) => new { test = $"h: {h}" });


// Map an endpoint with a header parameter that has a different name than the parameter in the handler function, and demonstrate how to use the HeaderParam attribute to bind them together
handlerConfiguration.MapGet("/map-header3", ([HeaderParam(Name = "header-param", IsRequired = false)] string h) => new { test = $"header-param: {h}" });


// Map an endpoint that demonstrates how to write a custom response directly to the HttpContext.Response object, which allows for more control over the response (e.g. setting custom status codes, headers, etc.)
// There is no need to set any attributes on the HttpContext parameter, since this type is recognized by the framework and will be automatically injected with the current HttpContext when the handler function is called
handlerConfiguration.MapGet("/get-custom-response", async (HttpContext httpContext) => 
{
    httpContext.Response.StatusCode = 200;
    httpContext.Response.ContentType = "text/plain";
    await httpContext.Response.WriteAsync("This is a custom response");

    // There is no need to return anything from this handler function, since we have already written the response directly to the HttpContext.Response object.
    // If we did return something, it would be ignored in this case.
});


// Map an endpoint that demonstrates how to access the handler configuration object in the handler function,
// which can be useful for accessing custom configuration values defined in the MyAdvancedHttpHandlerConfig class.
// In this example MyAdvancedHttpHandlerConfig is the T in AdvancedHttpHandlerBase<T>,
// and does not need to have any attributes applied to be mapped as a parameter in the handler function,
// since it's mapping is handled by the framework based on the generic type parameter of the AdvancedHttpHandlerBase class.
handlerConfiguration.MapGet("/get-step-config", (MyAdvancedHttpHandlerConfig config) =>
{
    return config;
});


// Map an endpoint that demonstrates how to use the CancellationToken parameter to handle request cancellation.
// There is no need to set any attributes on the CancellationToken parameter, since this type is recognized by the framework
// and will be automatically injected with the appropriate CancellationToken that is triggered when the request is cancelled (e.g. when the client disconnects).
handlerConfiguration.MapGet("/map-cancellation-token", (CancellationToken cancellationToken) => cancellationToken.ThrowIfCancellationRequested());

public class  MyRequestObject
{
    // This property is required by default, so if you try to call the endpoint that uses this object
    // without providing a value for this property, it will return a 400 Bad Request response
    // Empty strings are also considered invalid values for this property, so if you provide an empty string, it will also return a 400 Bad Request response
    [System.ComponentModel.DataAnnotations.Required]
    public string? name { get; set; }
  

    // This property is optional, so you can call the endpoint that uses this object without providing a value for this property, and it will work fine
    // However, if you do provide a value for this property, it must not exceed 100 characters in length, otherwise it will return a 400 Bad Request response
    [System.ComponentModel.DataAnnotations.MaxLength(100)]
    public string? desctiption { get; set; }
  

    // This property is required and must contain at least one element, so if you try to call the endpoint that uses this object without providing a value for this property,
    // or if you provide an empty array, it will return a 400 Bad Request response
    [System.ComponentModel.DataAnnotations.Required]
    [System.ComponentModel.DataAnnotations.MinLength(1)]
    public string[]? notes { get; set; }
}

// This demonstrates how to return a standard error response with a specific status code and message by throwing a LinkWebApiException with the appropriate parameters.
handlerConfiguration.MapGet("/return-standard-error", () =>
{
    throw new LinkWebApiException(418, message: "I'm a teapot");
});

// This demonstrates how to return a custom error response with a custom status code, message, and response body by throwing a LinkWebApiException with the appropriate parameters.
handlerConfiguration.MapGet("/return-custom-error", () =>
{
    throw new LinkWebApiException(418, responseObject: new { error = "Error was: I'm a teapot" }, message: "I'm a teapot");
});

// Demonstrates how to use the documentation configuration to add rich documentation for an endpoint, which will be shown in the generated API documentation.
handlerConfiguration.MapGet("/say-hello/{name}", ([RouteParam] string name) => new MyResponseObject { responseMessage = $"Hello {name}" })
    .ConfigureDocumentation(doc => 
    {
        doc.AddSummary("Say hello to the client");
        doc.AddDescription("Receives a name from the client, which is used to ro return a 'Hello' message");
        doc.ConfigureParameters(parms =>
        {
            // Route parameter declared. Similar methods are available for query and header parameters as well.
            parms.AddRouteParameter("name", "Used to address the client by name");
        });
        // Declares a response example for status code 200 based on the MyResponseObject class, which will be shown in the documentation.
        // The framework will automatically generate an example response based on the structure of the MyResponseObject class.
        doc.AddGeneratedResponse(200, "Successful response", typeof(MyResponseObject));
        // Declares a concrete response example for status code 418, which will be shown in the documentation.
        doc.AddResponse(418, "I'm a teapot response", new { error = "Error was: I'm a teapot" });
    });