In this article, we will learn about the minimal API concept in .NET Core.
What is a Minimal API?
A Minimal API is a simplified approach to building APIs in .NET, introduced in .NET 6. It streamlines the process of creating HTTP services by reducing boilerplate code and configuration, making it easier to set up and maintain. This approach is particularly beneficial for microservices, small applications, or rapid prototyping.
Key Features of Minimal API
- Simplified Configuration: Minimal APIs reduce the amount of boilerplate code needed to set up an API.
- Top-Level Statements: Allows writing API code without the need for a
Startup
class or aProgram
class. - Lightweight: Ideal for small, quick applications or microservices where a full MVC pattern might be overkill.
- Enhanced Performance: With fewer abstractions, minimal APIs can lead to better performance.
Creating a Minimal API in .NET Core
Here’s a step-by-step guide to creating a Minimal API in .NET Core
Step 1: Setting Up Your Project
First, create a new .NET Core project. You can use the .NET CLI to do this:
dotnet new web -o MinimalApiDemo
cd MinimalApiDemo
Step 2: Adding Minimal API Code
Open the Program.cs
file and replace its content with the following code:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/weather", () =>
{
var weatherSummaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateTime.Now.AddDays(index),
Random.Shared.Next(-20, 55),
weatherSummaries[Random.Shared.Next(weatherSummaries.Length)]
))
.ToArray();
return forecast;
});
app.Run();
record WeatherForecast(DateTime Date, int TemperatureC, string Summary);
Step 3: Running the Application
Run the application using the following command:
dotnet run
The API will start, and you can test it by navigating to http://localhost:5000
in your browser or using a tool like curl
or Postman.
Detailed Explanation
WebApplication.CreateBuilder
: Initializes the web application builder with default settings.builder.Build()
: Builds the application.app.MapGet
: Maps HTTP GET requests to the specified URL path. The first endpoint returns “Hello, World!” when accessing the root URL ("/"
).- Weather Forecast Endpoint: A more complex endpoint that returns a list of weather forecasts. The forecasts are generated randomly for demonstration purposes.
record WeatherForecast
: Defines a record type for weather forecast data. Records are a concise way to create immutable objects with value-based equality.
POST Operation with Minimal API in .NET Core
The POST operation in a Minimal API is used to create new resources on the server. It typically involves accepting data from the client, processing it, and storing it in a database or other storage mechanisms.
Steps to Implement a POST Operation
- Set Up the Project: Ensure you have a minimum .NET 6 project set up.
- Define the Model: Create a model that represents the data structure.
- Implement the POST Endpoint: Define a POST endpoint that accepts data and processes it.
Sample Code for a POST Operation
Step 1: Setting Up the Project
Create a new .NET 6 or greater version project if you haven’t already:
dotnet new web -o MinimalApiPostDemo
cd MinimalApiPostDemo
Step 2: Define the Model
Create a model class to represent the data structure. For example, let’s create a TodoItem
model:
// TodoItem.cs
public record TodoItem(int Id, string Title, bool IsCompleted);
Step 3: Implement the POST Endpoint
Modify the Program.cs
file to include a POST endpoint:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var todoItems = new List<TodoItem>();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/todos", () => todoItems);
app.MapPost("/todos", (TodoItem todoItem) =>
{
todoItems.Add(todoItem);
return Results.Created($"/todos/{todoItem.Id}", todoItem);
});
app.Run();
public record TodoItem(int Id, string Title, bool IsCompleted);
Explanation of the Code
- Setup: The
WebApplication.CreateBuilder(args)
initializes the web application builder with default settings, andbuilder.Build()
builds the application. - In-Memory List: An in-memory list (
todoItems
) is used to storeTodoItem
instances for demonstration purposes. - GET Endpoints:
app.MapGet("/", () => "Hello, World!")
: A simple endpoint to check if the API is running.app.MapGet("/todos", () => todoItems)
: Returns the list ofTodoItem
instances.
- POST Endpoint:
app.MapPost("/todos", (TodoItem todoItem) => ...)
maps POST requests to the/todos
URL.- The
todoItem
parameter is automatically bound from the request body. - The new
todoItem
is added to thetodoItems
list. Results.Created($"/todos/{todoItem.Id}", todoItem)
returns a 201 Created response with the location of the newly created resource.
Running the Application
Run the application using the following command:
dotnet run
You can test the POST operation using a tool like curl
or Postman. For example, with curl
:
curl -X POST https://localhost:5001/todos -H "Content-Type: application/json" -d '{"id":1,"title":"Learn Minimal API","isCompleted":false}'
This command sends a POST request to the /todos
endpoint with a JSON payload representing a TodoItem
.
Benefits of Minimal APIs for POST Operations
- Simplicity: Minimal setup and boilerplate code.
- Ease of Use: Straightforward to define and map endpoints.
- Performance: Less overhead compared to full MVC applications.
- Flexibility: Suitable for various applications, from microservices to small APIs.
File Upload with Minimal API in .NET Core
If we want to handle file uploads as well, we can manage the code to include file processing with .NET Core minimal API.
Let’s see this in action:
app.MapPost("/upload", async (HttpRequest request) =>
{
if (!request.HasFormContentType)
{
return Results.BadRequest("Form content type is required.");
}
var form = await request.ReadFormAsync();
var formData = form["data"];
var files = form.Files; // This will give you the collection of files
foreach (var file in files)
{
// Process each file as needed
}
return Results.Ok(new { Message = "Form data and files received", Data = formData.ToString(), FileCount = files.Count });
});
Here, the code snippet will handle both form fields and file uploads, making the minimal API more versatile for various use cases.
Benefits of Using Minimal API in .NET Core
- Reduced Complexity: Less boilerplate code means faster development and easier maintenance.
- Performance: Fewer abstractions can lead to improved performance.
- Flexibility: Suitable for a variety of applications, from microservices to small APIs.
- Ease of Use: Simple and straightforward, making it accessible to developers of all skill levels.
Conclusion
Minimal APIs in .NET 6 offer a streamlined, efficient way to build HTTP services. They are particularly useful for small applications, microservices, or rapid prototyping, where the full power of ASP.NET Core MVC might not be necessary. With minimal configuration and a straightforward approach, developers can quickly create performant APIs.
Keep Following: SharePointCafe.NET