Minimal APIs vs Controller APIs: SerializerOptions.WriteIndented = true

Another thing added in ASP.NET Core / .NET 7.0 (yeah, I know it's been a while since it was released), is the "ConfigureHttpJsonOptions" extension method that lets us add JSON options to the services collection / dependency injection container. The setting that caught my eye is "WriteIndented = true". This gives a nice pretty output for JSON coming back from our APIs.

This is the difference between:

{"id":3,"givenName":"Leela","familyName":"Turanga","startDate":"1999-03-28T00:00:00-08:00","rating":8,"formatString":"{1} {0}"}

and

{
  "id": 3,
  "givenName": "Leela",
  "familyName": "Turanga",
  "startDate": "1999-03-28T00:00:00-08:00",
  "rating": 8,
  "formatString": "{1} {0}"
}

You may not want this because of the extra whitespace characters that have to come down the wire. But for the things that I work with, I want the pretty printing!

The good news is that in .NET 7.0, the new "ConfigureHttpJsonOptions" method lets us set this up (among quite a few other settings).

To use it, we just add the options to the Services in the Program.cs file of our project.

    // Set JSON indentation
    builder.Services.ConfigureHttpJsonOptions(
        options => options.SerializerOptions.WriteIndented = true);

You can check the documentation for JsonSerializerOptions Class to see what other options are available.

But there's a catch:

ConfigureHttpJsonOptions does work for Minimal APIs.
ConfigureHttpJsonOptions does not work for Controller APIs. 

Let's take a look at that. For code samples, you can check out this repository: https://github.com/jeremybytes/controller-vs-minimal-apis.

Sample Application

The sample code contains a "MinimalApi" project and a "ControllerApi" project. These were both started as fresh projects using the "dotnet new webapi" template (and the appropriate flags for minimal/controller). Both projects get their data from a 3rd project ("People.Library") that provides some hard-coded data.

Here is the minimal API that provides the data above:

    app.MapGet("/people/{id}",
        async (int id, IPeopleProvider provider) => await provider.GetPerson(id))
        .WithName("GetPerson")
        .WithOpenApi();

And here's the controller API:

    [HttpGet("{id}", Name = "GetPerson")]
    public async Task<Person?> GetPerson(
        [FromServices] IPeopleProvider provider, int id)
    {
        // This may return null
        return await provider.GetPerson(id);
    }

Both of these call the "GetPerson" method on the provider and pass in the appropriate ID.

Testing the Output

To test the output, I created a console application (the "ServiceTester" project). I did this to make sure I was not getting any automatic JSON formatting from a browser or other tool.

I created an extension method on the Uri type to make calling easier. You can find the complete code in the RawResponseString.cs file.

    public static async Task<string> GetResponse(
        this Uri uri, string endpoint)

The insides of this method make an HttpClient call and return the response.

The calling code is in the Program.cs file of the ServiceTester project.

        Uri controllerUri = new("http://localhost:5062");
        Uri minimalUri = new("http://localhost:5194");

        // Minimal API Call
        Console.WriteLine("Minimal /people/3");
        var response = await minimalUri.GetResponse("/people/3");
        Console.WriteLine(response);

        Console.WriteLine("----------");

        // Controller API Call
        Console.WriteLine("Controller /people/3");
        response = await controllerUri.GetResponse("/people/3");
        Console.WriteLine(response);

        Console.WriteLine("----------");

This creates 2 URIs (one for each API), calls "GetResponse" for each and then outputs the string to the console.

This application was also meant to show some other differences between Minimal APIs and Controller APIs. These will show up in future articles.

Without "WriteIndented = true"

Here is the output of the ServiceTester application without making any changes to the settings of the API projects.

Note that both the MinimalApi and ControllerApi services need to be running in order for the ServiceTester application to work. (I start the services in separate terminal tabs just so I can keep them running while I do my various tests.)

Minimal /people/3
{"id":3,"givenName":"Leela","familyName":"Turanga","startDate":"1999-03-28T00:00:00-08:00","rating":8,"formatString":"{1} {0}"}
----------
Controller /people/3
{"id":3,"givenName":"Leela","familyName":"Turanga","startDate":"1999-03-28T00:00:00-08:00","rating":8,"formatString":"{1} {0}"}
----------

So let's change some settings.

"WriteIndented = true"

So let's add the options setting to both projects (MinimalApi/Program.cs and ControllerApi/Program.cs):

    // Set JSON indentation
    builder.Services.ConfigureHttpJsonOptions(
        options => options.SerializerOptions.WriteIndented = true);

Then we just need to restart both services and rerun the ServiceTester application:

    Minimal /people/3
    {
      "id": 3,
      "givenName": "Leela",
      "familyName": "Turanga",
      "startDate": "1999-03-28T00:00:00-08:00",
      "rating": 8,
      "formatString": "{1} {0}"
    }
    ----------
    Controller /people/3
    {"id":3,"givenName":"Leela","familyName":"Turanga","startDate":
    "1999-03-28T00:00:00-08:00","rating":8,"formatString":"{1} {0}"}
    ----------

This shows us that the pretty formatting is applied to the Minimal API output, but not to the Controller API output.

So What's Going On?

I found out about this new setting the same way as the one in the previous article -- by hearing about it in a conference session. I immediately gave it a try and saw that it did not work on the API I was experimenting with. After few more tries, I figured out that the setting worked with the Minimal APIs that I had, but not the Controller APIs. (And I did try to get it to work with the Controller APIs in a whole bunch of different ways.)

Eventually, I came across this snippet in the documentation for the "ConfigureHttpJsonOptions" method (bold is mine):

Configures options used for reading and writing JSON when using Microsoft.AspNetCore.Http.HttpRequestJsonExtensions.ReadFromJsonAsync and Microsoft.AspNetCore.Http.HttpResponseJsonExtensions.WriteAsJsonAsync. JsonOptions uses default values from JsonSerializerDefaults.Web.

This tells us that these options are only used in certain circumstances. In this case, specifically when WriteAsJsonAsync is called.

I have not been able to find what uses "WriteAsJsonAsync" and what does not. Based on my observations, I assume that Minimal APIs do use WriteAsJsonAsync and Controller APIs do not use WriteAsJsonAsync.

So I add another item to my list of differences between Minimal APIs and Controller APIs. I guess it's time to publish this list somewhere.

Wrap Up

So, back to the beginning:

ConfigureHttpJsonOptions does work for Minimal APIs.
ConfigureHttpJsonOptions does not work for Controller APIs. 

It would be really nice if these capabilities matched or if there was a note somewhere that said "This is for minimal APIs".

Hopefully this will save you a bit of frustration in your own code. If you want to use "WriteIntented = true", then you will need to use Minimal APIs (not Controller APIs).

Happy Coding!