HTTP Endpoints #

First, a little terminology about Wolverine HTTP endpoints. Consider the following endpoint method:

[WolverinePost("/question")]
public static Results PostJson(Question question)
{
    return new Results
    {
        Sum = question.One + question.Two,
        Product = question.One * question.Two
    };
}

^{snippet source | anchor}

In the method signature above, Question is the "request" type (the payload sent from the client to the server) and Answer is the "resource" type (what is being returned to the client). If instead that method were asynchronous like this:

[WolverinePost("/question2")]
public static Task<Results> PostJsonAsync(Question question)
{ 
    var results = new Results
    {
        Sum = question.One + question.Two,
        Product = question.One * question.Two
    };

    return Task.FromResult(results);
}

^{snippet source | anchor}

The resource type is still Answer. Likewise, if an endpoint returns ValueTask<Answer>, the resource type is also Answer, and Wolverine will worry about the asynchronous (or return Task.CompletedTask;) mechanisms for you in the generated code.

Routing #

Wolverine HTTP endpoints need to be decorated with one of the [WolverineVerb("route")] attributes that expresses the routing argument path in standard ASP.Net Core syntax (i.e., the same as when using MVC Core or Minimal API).

If a parameter argument to the HTTP handler method exactly matches a route argument, Wolverine will treat that as a route argument and pass the route argument value at runtime from ASP.Net Core to your handler method. To make that concrete, consider this simple case from the test suite:

sample: sample_using_string_route_parameter

In the sample above, the name argument will be the value of the route argument at runtime. Here's another example, but this time using a numeric value:

[WolverineGet("/age/{age}")]
public static string IntRouteArgument(int age)
{
    return $"Age is {age}";
}

^{snippet source | anchor}

The following code snippet from WolverineFx.Http itself shows the valid route parameter types that are supported at this time:

public static readonly Dictionary<Type, string> TypeOutputs = new Dictionary<Type, string>
{
    {typeof(bool), "bool"},
    {typeof(byte), "byte"},
    {typeof(sbyte), "sbyte"},
    {typeof(char), "char"},
    {typeof(decimal), "decimal"},
    {typeof(float), "float"},
    {typeof(short), "short"},
    {typeof(int), "int"},
    {typeof(double), "double"},
    {typeof(long), "long"},
    {typeof(ushort), "ushort"},
    {typeof(uint), "uint"},
    {typeof(ulong), "ulong"},
    {typeof(Guid), typeof(Guid).FullName},
    {typeof(DateTime), typeof(DateTime).FullName},
    {typeof(DateTimeOffset), typeof(DateTimeOffset).FullName}
};

^{snippet source | anchor}

Working with QueryString #

Wolverine supports passing query string values to your HTTP method arguments for the exact same set of value types supported for route arguments. In this case, Wolverine treats any value type parameter where the parameter name does not match a route argument name as coming from the HTTP query string.

When Wolverine does the runtime matching, it's using the exact parameter name as the query string key. Here's a quick sample:

[WolverineGet("/querystring/string")]
public static string UsingQueryString(string name) // name is from the query string
{
    return name.IsEmpty() ? "Name is missing" : $"Name is {name}";
}

^{snippet source | anchor}

And the corresponding tests:

[Fact]
public async Task use_string_querystring_hit()
{
    var body = await Scenario(x =>
    {
        x.Get.Url("/querystring/string?name=Magic");
        x.Header("content-type").SingleValueShouldEqual("text/plain");
    });
    
    body.ReadAsText().ShouldBe("Name is Magic");
}

[Fact]
public async Task use_string_querystring_miss()
{
    var body = await Scenario(x =>
    {
        x.Get.Url("/querystring/string");
        x.Header("content-type").SingleValueShouldEqual("text/plain");
    });
    
    body.ReadAsText().ShouldBe("Name is missing");
}

^{snippet source | anchor}

Working with JSON #

As explained up above, the "request" type to a Wolverine endpoint is the first argument that is:

1. Concrete
2. Not one of the value types that Wolverine considers for route or query string values
3. Not marked with [FromServices] from ASP.Net Core

If a parameter like this exists, that will be the request type, and will come at runtime from deserializing the HTTP request body as JSON.

Likewise, any resource type besides strings will be written to the HTTP response body as serialized JSON.

In this sample endpoint, both the request and resource types are dealt with by JSON serialization. Here's the test from the actual Wolverine codebase:

[Fact]
public async Task post_json_happy_path()
{
    // This test is using Alba to run an end to end HTTP request
    // and interrogate the results
    var response = await Scenario(x =>
    {
        x.Post.Json(new Question { One = 3, Two = 4 }).ToUrl("/question");
        x.WithRequestHeader("accepts", "application/json");
    });

    var result = await response.ReadAsJsonAsync<Results>();
    
    result.Product.ShouldBe(12);
    result.Sum.ShouldBe(7);
}

^{snippet source | anchor}

Returning Strings #

To create an endpoint that writes a string with content-type = "text/plain", just return a string as your resource type, so string, Task<string>, or ValueTask<string> from your endpoint method like so:

public class HelloEndpoint
{
    [WolverineGet("/")]
    public string Get() => "Hello.";
}

^{snippet source | anchor}

Using IResult #

Wolverine will execute an ASP.Net Core IResult object returned from an HTTP endpoint method.

[WolverineGet("/choose/color")]
public IResult Redirect(GoToColor request)
{
    switch (request.Color)
    {
        case "Red":
            return Results.Redirect("/red");
        
        case "Green":
            return Results.Redirect("/green");

        default:
            return Results.Content("Choose red or green!");
    }
}

^{snippet source | anchor}

Using IoC Services #

Wolverine HTTP endpoint methods happily support "method injection" of service types that are known in the IoC container. If there's any potential for confusion between the request type argument and what should be coming from the IoC container, you can decorate parameters with the [FromServices] attribute from ASP.Net Core to give Wolverine a hint. Otherwise, Wolverine is asking the underlying Lamar container if it knows how to resolve the service from the parameter argument.

Accessing HttpContext #

Simply expose a parameter of any of these types to get either the current HttpContext for the current request or children members of HttpContext:

1. HttpContext
2. HttpRequest
3. HttpResponse
4. CancellationToken
5. ClaimsPrincipal

You can also get at the trace identifier for the current HttpContext by a parameter like this:

[WolverineGet("/http/identifier")]
public string UseTraceIdentifier(string traceIdentifier)
{
    return traceIdentifier;
}

^{snippet source | anchor}