Working with minimal APIs in .NET

If you’re building cloud-native applications with microservices, they need to be small. You don’t want code that comes with enough dependencies and required libraries to turn something that should be able to scale in milliseconds into megabytes of code. Small services deploy faster, scaling applications quickly, reducing latency, and ensuring a consistent user experience.

Much of the dead weight in APIs is part and parcel of using application frameworks designed for large-scale, complex applications where you need all that code to deliver the necessary performance and capabilities. But not every application needs to support all those use cases. If you only need to return a single value or a string when an API is called, you want something as minimalist as the data you’re delivering.

Introducing minimal APIs

Microsoft introduced minimal APIs with.NET 6, providing an alternative to ASP.NET Core’s Web API, and the company has continued to add features with each new release of the platform. Designed to implement the MVC design pattern across REST APIs, the Web API can be complex, implementing controllers for all the possible calls to an API. Minimal APIs remove the overhead associated with implementing controllers.

The result is a lot simpler and, in most cases, easier to understand. You only need to implement the API endpoints you’re using, handling basic CRUD functions or simple function calls. You can build minimal APIs into any.NET application, and they’re particularly suitable for use in Kubernetes-hosted.NET containers or via Azure’s App Service platform as a service tool. It’s possible to start simple and build out complex, secure APIs.

Minimal APIs can be built in any.NET development environment, with Microsoft providing guidance for both Visual Studio and Visual Studio Code. Tools like JetBrains’ Rider will also work, using current releases of the.NET SDKs.

Getting started

Building a minimal API-based application is relatively simple. There’s no need to add complex scaffolding. All you need to do is declare your web application and then add your API’s route, along with constructing responses. For example, a minimal API that returns a string can be written in three lines of code, with the API defined in a single MapGet operation.

There’s support for all the essential HTTP operations: MapGet, MapPut, MapPost, and MapDelete. These will allow you to build most of the common API functions and manage the payloads for your code. Client applications and views will need to implement the HTTP operation created by the mapping. More complex operations can use the MapMethods to support other HTTP operations.

There’s no need to write code to manage serialization, so, for example, if you’re using a MapPost endpoint and delivering a JSON object, it will automatically populate a.NET object with its contents.

Once a minimal API route has been matched,.NET fires up a route handler. This can be any form of method, though in most cases inline lambda expressions are an effective way to quickly handle and respond to inputs. Alternatively, you can define a function outside the minimal API and have the route handler call it.

In practice, if you’re building a minimal API as part of a microservice, you should look at using instance methods as route handlers. Here you can define a class to be called when a route is matched, running your application logic and returning content that will be delivered as the API response. There’s no reason why a minimal API can’t be treated much the same way as any.NET API implementation, and you can use your choice of coding styles.

Other route-handling options include catchalls, which reduce security risks by trapping errors and attacks and only allowing through calls that match defined routes. Other tools include support for ASP.NET Core’s route constraints. At the same time route groups simplify using authentication tools by bringing together endpoints with the same prefix.

The result is a flexible way of defining what can be complex endpoints, supporting multiple APIs with many different operations while keeping code readable. You can use much of this capability to manage access to public and private endpoints.

You’re not limited to basic call and response pairs, as it’s easy to quickly replace elements of an API URL with parameters, giving you a consistent way to map routes to data. All you need to do is declare the appropriate variables and then use them in your code to construct the response. If you’ve used any routing-based API tools, such as Node’s Express, you’ll find the approach familiar.

Delivering responses

Responses in.NET minimal APIs can be one of three types. The simplest is, of course, a string, but there’s support for any other type and for IResults. Strings are delivered as basic HTTP content, with a 200 success code and text/plain content in the message body. More complex responses can be delivered as types, which are serialized as JSON documents. This approach gets closer to the familiar RESTful JSON responses.

If you’re using OpenAPI descriptions for your endpoints, you are likely to want IResults, which can deliver strongly typed TypedResults. These are returned as objects, along with the metadata. This approach makes it easier to write tests and ensure your code can be tested as part of a CI/CD pipeline.

It’s great to have the ability to use result helpers to control the output of a minimal API. These are supported by both Results and TypedResults, so you can quickly use the JSON operator to return results as JSON. Other options let you force a status code or a 500 server error. One setting supports streamed data, so you can use minimal APIs for media or even deliver file-based content.

There’s a lot of flexibility, which is to be expected from.NET. Microsoft is aware of the wide variety of use cases it needs to support, and that’s as important for minimal API-based applications as for those using controllers. You need to be able to deliver any and all possible responses, from basic text to full web applications.

Building clients for minimal APIs

At heart, minimal APIs offer a basic route definition with support for parameters, with services consumed by familiar REST calls. This allows you to use standard HTTP libraries in clients so you’re not limited to web front ends.

Interestingly, if you’re using a web front end with a minimal API, it’s possible to bind a form to an API. This can be as simple as using a POST operation to a minimal API route. As form inputs can be susceptible to cross-site-request forgery attacks, you need to write code to support anti-forgery tokens. Validation is handled automatically, but you will need to add the appropriate token to your form submission, usually in a hidden field.

There are tools in both Razor and ASP.NET Core MVC to create and manage the tokens. This won’t be an issue with a traditional API call, as you can add alternate verification methods for client applications and services.

APIs have been an important building block for years, and thanks to cloud-native development they’re now a foundational tool for modern development. Having more than one way to build an API in a framework is important, as it allows us to choose what’s right for a specific application or component..NET’s minimal APIs help us build code the way we want without unnecessary overhead.