Minimal API in ASP.NET Core

Back to: ASP.NET Core Web API Tutorials

Minimal API in ASP.NET Core

In this article, I will discuss how to implement Minimal APIs in ASP.NET Core Application. Please read our previous article discussing Unit Testing in ASP.NET Core Web API.

What is the Minimal API in ASP.NET Core?

Minimal APIs are a new streamlined way to build HTTP APIs using ASP.NET Core (introduced in .NET 6) that emphasizes simplicity, speed, and minimal repetitive code. They are designed to help developers quickly create simple API endpoints, especially for smaller projects or microservices, without the need for all the infrastructure (like controllers, attributes, and extensive configuration) required by traditional ASP.NET Core MVC. Minimal APIs allow us to define endpoints directly in the Program.cs file using a more functional and simpler syntax.

Key Features of Minimal API:

• Lightweight Approach: Minimal APIs eliminate the need to create separate controller classes or explicitly configure MVC routing. You need to write small, focused code snippets to define HTTP methods (GET, POST, PUT, DELETE) and the corresponding request handlers.
• Functional Approach: Instead of the object-oriented controller/action model, Minimal APIs encourage a functional style. Endpoints are defined using lambdas or delegates that directly handle HTTP requests and return responses.
• Reduced Dependencies: Minimal APIs reduce the dependencies and complexity involved in setting up a project. They use the existing ASP.NET Core middleware pipeline but do not require the MVC framework to be loaded unless explicitly needed.
• Focused Use Case: This approach is ideal when you want to quickly build simple APIs without worrying about the complete MVC infrastructure, making it perfect for microservices, serverless functions, or backend APIs that require just a few endpoints.

Example:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () => "Hello Minimal API!");

app.Run();

This example defines a GET endpoint /hello that returns a simple string without creating any controller class.

How to Create a Minimal API Project in ASP.NET Core?

Let’s create a Minimal API in ASP.NET Core that performs CRUD (Create, Read, Update, Delete) operations on an Employee model. Open Visual Studio and click the “Create a new project” option, as shown in the image below.

Once you click the “Create a new project” option, it will open the “Create a new project” window. Here, you need to select the ASP.NET Core Web API template, which uses C# as the programming language, and then click the Next button, as shown in the image below.

Once you click the Next button, the “Configure Your New Project” window will open. Here, you need to specify the Project name (MinimalAPIDemo) and the location where you want to create the project. Finally, click the Next button, as shown in the image below.

Once you click the Next button, the Additional Information window will open. Here, you need to select the Target .NET version. The authentication Types. Whether you want to configure HTTPS and enable Docker, etc., we will use .NET 8. Therefore, select .NET 8 as the Framework. We will not use any authentication at this time, so select ‘None’ as the authentication type. Then, apart from configuring HTTPS and enabling OpenAPI support, please unselect all the remaining checkboxes. To develop a Minimal API, do not select the “Use Controllers” checkbox.

Once you click on the Create button, Visual Studio will create the ASP.NET Core Web API project.

Create the Employee Model

First, create a folder named Models in the project root directory. Then, inside the Models folder, create a new class file named Employee.cs, and then copy and paste the following code. This Employee class contains four properties: Id, Name, Position, and Salary. It will be used as the data model for our API.

namespace MinimalAPIDemo.Models
{
    public class Employee
    {
        public int Id { get; set; }
        public string Name { get; set; } = null!;
        public string Position { get; set; } = null!;
        public decimal Salary { get; set; }
    }
}

How to Implement Minimal API in ASP.NET Core

Minimal APIs in ASP.NET Core allow us to define HTTP endpoints directly inside the Program.cs file, using methods like MapGet, MapPost, MapPut, and MapDelete. Each method corresponds to a specific HTTP verb, helping to build RESTful API operations in a concise and readable way. Let us have a look at each method and its usage in Minimal APIs.

MapGet — Handling HTTP GET Requests

Retrieve or fetch data without changing the server state. It is used when we want to read or list data, such as returning all employees or a specific employee by their ID. Suppose you want to retrieve a list of all employees or an individual employee by their ID.

Here, the first endpoint returns all employees. The second endpoint takes an ID from the route, fetches the employee, and returns HTTP 200 if found, or 404 if not.

MapPost — Handling HTTP POST Requests

The MapPost method creates a new resource. It is used when clients send new data to your API that should be added to the database or an in-memory collection. POST requests usually carry data in the request body, which Minimal APIs automatically bind to method parameters or DTOs (Data Transfer Objects). For example, create a new employee record.

Here, the new employee details are sent in the request body. The API adds the employee and returns HTTP 201 Created with a URI to the new resource.

MapPut — Handling HTTP PUT Requests

The MapPut method updates an existing resource. It is used when we want to replace or update all details of a resource identified by its ID. Calling the same PUT request multiple times should not produce different results. The resource is either created or fully updated. For example, update an employee’s details.

Here, the client sends the updated employee details in the body of the message. The API finds the existing employee by ID and updates it, or returns a 404 error if it is not found. The typical response is 204 No Content, indicating the update succeeded with no return body.

MapDelete — Handling HTTP DELETE Requests

The MapDelete method deletes an existing resource. It is used when we want to permanently remove a resource. For example, delete an employee by their ID.

Here, the client provides the ID of the employee to delete. The API deletes the employee if it exists and returns a 204 No Content response. If the employee does not exist, it returns a 404 Not Found error.

Example to Understand Minimal APIs in ASP.NET Core

Now, open Program.cs and set up the Minimal API endpoints that handle CRUD operations on an in-memory list of employees. So, please modify the Program class as follows. The following code is self-explained, so please read the comment lines for a better understanding.

using MinimalAPIDemo.Models;
namespace MinimalAPIDemo
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Configure JSON options to disable camel casing
            builder.Services.ConfigureHttpJsonOptions(options =>
            {
                // disables camelCase, uses PascalCase as-is
                options.SerializerOptions.PropertyNamingPolicy = null;
            });

            // Add services needed for API documentation (Swagger)
            builder.Services.AddEndpointsApiExplorer();
            builder.Services.AddSwaggerGen();

            var app = builder.Build();

            // Enable Swagger UI only in the development environment
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }

            // In-memory list simulating a database of employees
            var employeeList = new List<Employee>
            {
                new Employee { Id = 1, Name = "John Doe", Position = "Software Engineer", Salary = 60000 },
                new Employee { Id = 2, Name = "Jane Smith", Position = "Project Manager", Salary = 80000 }
            };

            // ------------------- CRUD Operations -------------------

            // GET /employees - Retrieve all employees
            app.MapGet("/employees", () => {
                return employeeList;
            });

            // GET /employees/{id} - Retrieve a single employee by ID
            app.MapGet("/employees/{id}", (int id) =>
            {
                var employee = employeeList.FirstOrDefault(e => e.Id == id);
                return employee is not null ? Results.Ok(employee) : Results.NotFound();
            });

            // POST /employees - Create a new employee
            app.MapPost("/employees", (Employee newEmployee) =>
            {
                newEmployee.Id = employeeList.Count > 0 ? employeeList.Max(emp => emp.Id) + 1 : 1;
                employeeList.Add(newEmployee);
                return Results.Created($"/employees/{newEmployee.Id}", newEmployee);
            });

            // PUT /employees/{id} - Update an existing employee
            app.MapPut("/employees/{id}", (int id, Employee updatedEmployee) =>
            {
                if(id != updatedEmployee.Id)
                    return Results.BadRequest("Id Mismatch");
    
                var employee = employeeList.FirstOrDefault(emp => emp.Id == id);
                if (employee is null) 
                    return Results.NotFound();

                employee.Name = updatedEmployee.Name;
                employee.Position = updatedEmployee.Position;
                employee.Salary = updatedEmployee.Salary;
                return Results.Ok(employee);
            });

            // DELETE /employees/{id} - Delete an employee
            app.MapDelete("/employees/{id}", (int id) =>
            {
                var employee = employeeList.FirstOrDefault(emp => emp.Id == id);
                if (employee is null) 
                    return Results.NotFound();

                employeeList.Remove(employee);
                return Results.NoContent();
            });

            app.Run();
        }
    }
}

Now, run the application and access the above endpoints using client tools such as Swagger, Fiddler, and Postman; it should work as expected.

Important Notes About These Methods

• Direct Route and Handler Mapping: These methods define routes and their corresponding request handlers in a single location (Program.cs), eliminating the need for separate controller classes.
• Automatic Parameter Binding: Minimal APIs automatically bind route parameters (e.g., {id}) and request body content (e.g., JSON representing an Employee) to method parameters or objects.
• Return Types and Results: You can return POCO objects directly (which ASP.NET Core serializes as JSON) or use helpers like Results.Ok(), Results.NotFound(), and Results.Created() to return appropriate HTTP status codes along with data.
• Middleware Integration: These endpoint methods fully participate in ASP.NET Core’s middleware pipeline, allowing you to apply authentication, authorization, logging, exception handling, and other middleware before or after these handlers.

Dependency Injection in ASP.NET Core Minimal APIs:

Dependency injection in Minimal APIs is handled in a similar manner to traditional ASP.NET Core applications. Services are registered in the builder.Services collection and injected into endpoint handlers.

Now, let’s refactor our example and use dependency injection to handle Employee-related logic. For this, we will create a service class that encapsulates the employee management functionality. We will then register this service with the dependency injection container in ASP.NET Core and modify the endpoints to use this service.

Employee Repository Interface

First, create an interface named IEmployeeRepository.cs within the Models folder, and then copy and paste the following code. The following interface defines the contract for employee data operations.

namespace MinimalAPIDemo.Models
{
    public interface IEmployeeRepository
    {
        // Retrieve all employees
        List<Employee> GetAllEmployees();

        // Retrieve a single employee by their ID, or null if not found
        Employee? GetEmployeeById(int id);

        // Add a new employee and return the created employee with assigned ID
        Employee AddEmployee(Employee employee);

        // Update an existing employee by ID, return updated employee or null if not found
        Employee? UpdateEmployee(int id, Employee updatedEmployee);

        // Delete an employee by ID, returns true if deleted successfully, false otherwise
        bool DeleteEmployee(int id);
    }
}

Employee Repository Implementation

Next, create a class file named EmployeeRepository.cs within the Models folder and copy and paste the following code. The EmployeeRepository class implements the IEmployeeRepository interface and provides implementations for all methods defined in the IEmployeeRepository interface. The following is an in-memory implementation of the IEmployeeRepository for demo and testing purposes.

namespace MinimalAPIDemo.Models
{
    public class EmployeeRepository : IEmployeeRepository
    {
        // Internal list simulating persistent storage
        private readonly List<Employee> _employeeList;

        public EmployeeRepository()
        {
            // Initialize with sample employees to provide initial data
            _employeeList = new List<Employee>
            {
                new Employee { Id = 1, Name = "John Doe", Position = "Software Engineer", Salary = 60000 },
                new Employee { Id = 2, Name = "Jane Smith", Position = "Project Manager", Salary = 80000 }
            };
        }

        // Returns the entire list of employees
        public List<Employee> GetAllEmployees()
        {
            return _employeeList;
        }

        // Finds an employee by their unique ID or returns null if not found
        public Employee? GetEmployeeById(int id)
        {
            return _employeeList.FirstOrDefault(e => e.Id == id);
        }

        // Adds a new employee, automatically assigning a unique ID
        public Employee AddEmployee(Employee newEmployee)
        {
            // Assign ID as max existing ID + 1, or 1 if list is empty
            newEmployee.Id = _employeeList.Count > 0 ? _employeeList.Max(emp => emp.Id) + 1 : 1;

            _employeeList.Add(newEmployee);
            return newEmployee;
        }

        // Updates an existing employee; returns updated employee or null if not found
        public Employee? UpdateEmployee(int id, Employee updatedEmployee)
        {
            var employee = _employeeList.FirstOrDefault(emp => emp.Id == id);
            if (employee == null)
                return null;

            // Update fields individually to avoid replacing the whole object
            employee.Name = updatedEmployee.Name;
            employee.Position = updatedEmployee.Position;
            employee.Salary = updatedEmployee.Salary;

            return employee;
        }

        // Deletes employee by ID; returns true if deletion succeeded, else false
        public bool DeleteEmployee(int id)
        {
            var employee = _employeeList.FirstOrDefault(emp => emp.Id == id);
            if (employee == null)
                return false;

            _employeeList.Remove(employee);
            return true;
        }
    }
}

Using Repository in Minimal API Endpoints:

Next, modify the Program class as follows to use the EmployeeRepository. The EmployeeRepository is injected into the endpoints.

using MinimalAPIDemo.Models;
namespace MinimalAPIDemo
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Configure JSON options to disable camel casing
            builder.Services.ConfigureHttpJsonOptions(options =>
            {
                // disables camelCase, uses PascalCase as-is
                options.SerializerOptions.PropertyNamingPolicy = null;
            });

            // Add Swagger services for API documentation generation and UI
            builder.Services.AddEndpointsApiExplorer();
            builder.Services.AddSwaggerGen();

            // Register the EmployeeRepository as a singleton service
            // This allows dependency injection of IEmployeeRepository wherever needed
            builder.Services.AddSingleton<IEmployeeRepository, EmployeeRepository>();

            var app = builder.Build();

            // Enable Swagger UI only in the development environment for API testing
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }

            // -------------------- Minimal API Endpoints --------------------

            // GET /employees
            // Retrieves all employees as a list
            app.MapGet("/employees", (IEmployeeRepository employeeRepository) =>
                employeeRepository.GetAllEmployees()
            );

            // GET /employees/{id}
            // Retrieves a single employee by ID
            // Returns 200 OK with employee if found, otherwise 404 Not Found
            app.MapGet("/employees/{id}", (int id, IEmployeeRepository employeeRepository) =>
            {
                var employee = employeeRepository.GetEmployeeById(id);
                return employee is not null ? Results.Ok(employee) : Results.NotFound();
            });

            // POST /employees
            // Creates a new employee with details from the request body
            // Returns 201 Created with location header pointing to the new resource
            app.MapPost("/employees", (Employee newEmployee, IEmployeeRepository employeeRepository) =>
            {
                var createdEmployee = employeeRepository.AddEmployee(newEmployee);
                return Results.Created($"/employees/{createdEmployee.Id}", createdEmployee);
            });

            // PUT /employees/{id}
            // Updates an existing employee identified by ID
            // Returns 200 OK with updated employee, or 404 Not Found if employee doesn't exist
            app.MapPut("/employees/{id}", (int id, Employee updatedEmployee, IEmployeeRepository employeeRepository) =>
            {
                var employee = employeeRepository.UpdateEmployee(id, updatedEmployee);
                return employee is not null ? Results.Ok(employee) : Results.NotFound();
            });

            // DELETE /employees/{id}
            // Deletes an employee identified by ID
            // Returns 204 No Content on success or 404 Not Found if employee not found
            app.MapDelete("/employees/{id}", (int id, IEmployeeRepository employeeRepository) =>
            {
                var result = employeeRepository.DeleteEmployee(id);
                return result ? Results.NoContent() : Results.NotFound();
            });

            // Run the web application
            app.Run();
        }
    }
}

Now, run the application and test the endpoints. It should work as expected.

Request Validation in Minimal APIs:

In Minimal APIs, validating incoming request data is crucial to ensure that your API only processes valid information. Validation helps prevent bad data from causing errors or corrupting your application’s state. There are two main ways to validate requests in Minimal APIs:

• Data Annotation Attributes: Decorate your model properties with attributes like [Required], [StringLength], [Range], etc. This approach is simple, built-in, and great for straightforward validation needs.
• External Libraries (like FluentValidation): For more advanced, customizable validation scenarios, you can integrate libraries such as FluentValidation.

In this example, we will focus on Data Annotation-based validation—the simplest and most common approach for beginner and intermediate projects.

Employee Model with Data Annotations

Please, modify the Employee class as follows. Here, you can see that we have decorated the model properties with different data annotation attributes:

using System.ComponentModel.DataAnnotations;
namespace MinimalAPIDemo.Models
{
    // Represents an employee in the system.
    // Data annotation attributes are used for model validation.
    public class Employee
    {
        // Employee identifier, auto-generated internally, no validation needed here
        public int Id { get; set; }

        // Name is required and cannot exceed 100 characters
        [Required(ErrorMessage = "Name is required")]
        [StringLength(100, ErrorMessage = "Name cannot exceed 100 characters")]
        public string Name { get; set; } = null!;

        // Position is required and cannot exceed 50 characters
        [Required(ErrorMessage = "Position is required")]
        [StringLength(50, ErrorMessage = "Position cannot exceed 50 characters")]
        public string Position { get; set; } = null!;

        // Salary must be within a realistic range
        [Required(ErrorMessage = "Salary is required")]
        [Range(30000, 200000, ErrorMessage = "Salary must be between 30,000 and 200,000")]
        public decimal Salary { get; set; }
    }
}

Create a Generic Validation Helper

This helper class enables us to perform validation on any model object decorated with Data Annotations in a reusable and generic manner. Create a class file named ValidationHelper.cs within the Models folder and copy and paste the following code. The following class provides a generic method to validate objects using Data Annotation attributes.

using System.ComponentModel.DataAnnotations;
namespace MinimalAPIDemo.Models
{
    public static class ValidationHelper
    {
        // Validates the specified model instance.
        // T: Type of the model to validate
        // model: Model instance to validate.
        // validationResults: List of validation errors, if any.
        // returns True if the model is valid; otherwise, false.
        public static bool TryValidate<T>(T model, out List<ValidationResult> validationResults)
        {
            // Initialize the list to hold validation error results
            validationResults = new List<ValidationResult>();

            // If the model is null, return false and add a validation error
            if (model == null)
            {
                validationResults.Add(new ValidationResult("Model instance cannot be null."));
                return false;
            }

            // Create a ValidationContext for the model, which includes the model's metadata.
            var validationContext = new ValidationContext(model);

            // Perform validation and return the result.
            // Validate the model's properties based on their Data Annotation attributes

            // model: The instance of the object we want to validate.
            // validationContext: Provides metadata and context information required for the validation process.
            // validationResults: An output parameter (list) that will contain all validation errors found during the process.
            // true (validateAllProperties): When set to true, this tells the validator to check all properties of the object,
            //      not just those directly involved in the current context.
            //      This means nested objects and all annotated properties are validated.
            return Validator.TryValidateObject(model, validationContext, validationResults, true);
        }
    }
}

What is ValidationContext?

The ValidationContext is a class provided by .NET that carries information about the object being validated. It supplies metadata about the model instance (such as its type, property names, and values). When performing validation, the .NET Framework needs context about what it is validating. This includes:

• The actual model instance (model)
• The type of the model (e.g., Employee)

This context object is passed to the validation engine so it can understand what to validate and how. It acts as a container that carries both the object and any metadata that may influence validation.

Endpoints with Request Validation

Now, in our Minimal API endpoint, before processing the request data, we need to call ValidationHelper.TryValidate method on the incoming model to perform validation. Please modify Program.cs as follows. The endpoints will now validate incoming Employee models and return validation errors with proper HTTP 400 responses if validation fails.

using MinimalAPIDemo.Models;
namespace MinimalAPIDemo
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Configure JSON options to disable camel casing
            builder.Services.ConfigureHttpJsonOptions(options =>
            {
                // disables camelCase, uses PascalCase as-is
                options.SerializerOptions.PropertyNamingPolicy = null; 
            });

            // Add Swagger services for API documentation generation and UI
            builder.Services.AddEndpointsApiExplorer();
            builder.Services.AddSwaggerGen();

            // Register the EmployeeRepository as a singleton service
            // This allows dependency injection of IEmployeeRepository wherever needed
            builder.Services.AddSingleton<IEmployeeRepository, EmployeeRepository>();

            var app = builder.Build();

            // Enable Swagger UI only in the development environment for API testing
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }

            // -------------------- Minimal API Endpoints --------------------

            // GET /employees
            // Retrieves all employees as a list
            app.MapGet("/employees", (IEmployeeRepository employeeRepository) =>
                employeeRepository.GetAllEmployees()
            );

            // GET /employees/{id}
            // Retrieves a single employee by ID
            // Returns 200 OK with employee if found, otherwise 404 Not Found
            app.MapGet("/employees/{id}", (int id, IEmployeeRepository employeeRepository) =>
            {
                var employee = employeeRepository.GetEmployeeById(id);
                return employee is not null ? Results.Ok(employee) : Results.NotFound();
            });

            // POST /employees
            // Creates a new employee with details from the request body
            // Returns 201 Created with location header pointing to the new resource
            app.MapPost("/employees", (Employee newEmployee, IEmployeeRepository repo) =>
            {
                // Validate the incoming Employee object using ValidationHelper
                if (!ValidationHelper.TryValidate(newEmployee, out var validationErrors))
                {
                    // Return validation errors as a BadRequest response
                    return Results.BadRequest(new
                    {
                        Message = "Validation failed.",
                        Errors = validationErrors.Select(e => e.ErrorMessage)
                    });
                }

                var createdEmployee = repo.AddEmployee(newEmployee);
                return Results.Created($"/employees/{createdEmployee.Id}", createdEmployee);
            });

            // PUT /employees/{id}
            // Updates an existing employee identified by ID
            // Returns 200 OK with updated employee, or 404 Not Found if employee doesn't exist
            app.MapPut("/employees/{id}", (int id, Employee updatedEmployee, IEmployeeRepository repo) =>
            {
                if (!ValidationHelper.TryValidate(updatedEmployee, out var validationErrors))
                {
                    return Results.BadRequest(new
                    {
                        Message = "Validation failed.",
                        Errors = validationErrors.Select(e => e.ErrorMessage)
                    });
                }

                var employee = repo.UpdateEmployee(id, updatedEmployee);
                return employee is not null ? Results.Ok(employee) : Results.NotFound();
            });

            // DELETE /employees/{id}
            // Deletes an employee identified by ID
            // Returns 204 No Content on success or 404 Not Found if employee not found
            app.MapDelete("/employees/{id}", (int id, IEmployeeRepository employeeRepository) =>
            {
                var result = employeeRepository.DeleteEmployee(id);
                return result ? Results.NoContent() : Results.NotFound();
            });

            // Run the web application
            app.Run();
        }
    }
}

With the above changes in place, run the application and test the Post and Put endpoints where we have implemented validation. It should work as expected.

Limitations of Minimal API in ASP.NET Core.

Minimal APIs in ASP.NET Core provide a streamlined approach to developing small-scale HTTP APIs quickly. However, despite their simplicity and performance benefits, they have several limitations that might affect their suitability for certain types of applications:

Limited Support for Complex Applications:

Minimal APIs are best suited for lightweight applications, microservices, or APIs that do not require extensive middleware, sophisticated routing, or complex business logic. Applications with complex requirements, such as detailed validation, complex dependency injection scenarios, or sophisticated authorization policies, might become difficult to manage using Minimal APIs. As the complexity of the application increases, developers may face challenges in maintaining clean and organized code.

Absence of Advanced MVC Features:

Minimal APIs do not inherently support several advanced features available in MVC controllers, such as attribute routing, action filters (including authorization, resource filters, and exception filters), and built-in model validation mechanisms. For scenarios where these advanced features are critical, such as in-depth access control via attribute-based authorization or extensive validation logic, Minimal APIs may require significant manual implementation, leading to increased complexity and reduced maintainability.

Reduced Conventions and Increased Manual Setup:

The ASP.NET Core MVC framework uses well-defined conventions that enable the automatic configuration of various application aspects, including model binding, automatic routing, and response formatting. Minimal APIs lack some of these automatic conventions, requiring developers to manually set up routes, response handling, and validation logic. As a result, developers need a deeper understanding of how different ASP.NET Core components interact, which may increase the initial setup time and manual overhead.

Code Organization and Maintainability Challenges:

Due to the nature of Minimal APIs, where endpoints and route handlers are typically defined directly within a single file (Program.cs), the risk of cluttered and less organized codebases increases as applications scale. Without careful planning and deliberate organization strategies (such as separating handlers into distinct classes or files), Minimal APIs can become challenging to maintain, debug, and extend, particularly when handling numerous endpoints or routes.

Differences Between Minimal API and Controller-Based API

ASP.NET Core supports two primary approaches for building HTTP APIs: Minimal APIs and Controller-Based APIs. Both have distinct characteristics suited for different scenarios.

Minimal API Approach:

Minimal APIs emphasize simplicity and more straightforward syntax. Developers define routes and their corresponding request handlers directly in the Program.cs file. This method significantly reduces repetitive code, leading to quicker setup and deployment, ideal for small, focused APIs or microservices.

• Typically, define endpoints inline within a single file (Program.cs), offering simplicity and ease of use.
• Require significantly less configuration and initial setup, making them suitable for small applications.
• Offer high performance due to the streamlined pipeline and minimal overhead.
• Have limitations in handling complex features such as attribute routing, built-in filters (authorization, action, resource, exception), and model validation.

Controller-Based API Approach:

Controller-based APIs are built upon the traditional MVC (Model-View-Controller) architectural pattern. They group related actions logically within separate controller classes, enabling better structure, maintainability, and scalability for larger and more complex applications. Controllers inherently support attribute routing, filters, advanced model binding, and built-in validation mechanisms.

• Organize endpoints into controllers, grouping related operations to enhance clarity and maintainability.
• Utilize attribute-based routing, allowing clear and explicit route definitions.
• Support built-in filters, authorization, action filtering, model binding, and validation, significantly simplifying complex scenarios.
• Better suited for applications requiring extensive middleware support, complex business logic, comprehensive validation, or detailed endpoint management.

Recommendation

When choosing between Minimal APIs and Controller-Based APIs, consider the application’s complexity, maintainability requirements, and the necessity of advanced features. Minimal APIs are optimal for lightweight, performant, and rapidly developed APIs, while Controller-Based APIs are preferable for structured, maintainable, and feature-rich applications.

Minimal APIs in ASP.NET Core simplify the process of building HTTP APIs by reducing repetitive code, enabling developers to write quick and clean APIs with less code, while still maintaining the power and extensibility of the ASP.NET Core platform. They are handy for small projects, microservices, and scenarios where performance and simplicity are key.

In the next article, I will discuss How to Implement Error Handling and Logging in ASP.NET Core Minimal API with Examples. In this article, I explain how to implement Minimal APIs in ASP.NET Core Application with Examples. I hope you enjoy this article, Minimal API in ASP.NET Core.