Overview of Minimal APIs

In the expansive landscape of ASP.NET Core, "minimal API applications" function as compact yet powerful tools designed for rapidly constructing efficient HTTP APIs. These APIs natively support JSON data serialization, making them ideal for seamless interactions with single-page applications (SPAs) or mobile applications. They integrate seamlessly with leading frontend technologies like Angular, React.js, or mobile platforms to create fluid user experiences and efficient data exchange environments.

Embarking on the journey of API development with ASP.NET Core, minimal APIs provide a streamlined pathway. Compared to traditional MVC or Razor Pages approaches, they enable developers to define RESTful interfaces with minimal code and configuration. Developers are not required to navigate the complexities of controllers and view models; instead, they can design API blueprints—ranging from path design to behavior definition and request processing—directly in the project's core file, Program.cs, through a series of fluent calls and strategically placed anonymous functions.

Notably, minimal APIs embrace the philosophy of "simplicity without complexity." They encourage developers to avoid potentially burdensome traditional scaffolding approaches, directly declaring API functionality and purpose while eliminating redundant elements, resulting in clean and efficient program architecture.

Minimal APIs represent a standout feature in ASP.NET Core. With their exceptional simplification capabilities and flexibility, they significantly reduce developer burden, accelerate the creation, testing, and deployment of APIs, while ensuring code clarity and maintainability. In .NET 6 and subsequent versions, this approach has been further enhanced and promoted as the preferred method for building efficient, lightweight APIs.

Fundamental Concepts

HTTP APIs serve as "translators" in the digital world, utilizing the HTTP protocol as a common language to establish interaction standards. This enables diverse software systems—such as web pages, mobile applications, and other servers—to communicate through HTTP APIs for message transmission, data requests, and command execution.

Consider a scenario where a client wants to borrow a book from a server library. The client would send a request through the HTTP API: "Please lend me this book." Upon receiving the request, the library would locate the book according to the instructions and inform the client whether the book was found. This entire interaction process occurs through the HTTP API, ensuring smooth communication between both parties.

Key characteristics of HTTP APIs include:

• HTTP Protocol Compliance: Similar to telephone dialing rules, HTTP APIs specify standard formats for requests and responses. For example, GET methods are used for data retrieval, while POST methods are used for data submission.
• RESTful Style: Treats web resources as entities that can be manipulated through HTTP methods (GET, POST, PUT, DELETE) for CRUD operations.
• Statelessness: Each interaction occurs independently, with the server not retaining memory of previous interaction states.
• Usability: Provides documentation guidelines on how to send requests, which parameters to include, and response formats, facilitating quick adoption.
• Flexibility: Supports multiple data formats (such as JSON, XML) and interaction methods (synchronous, asynchronous) to accommodate various requirements.

In modern software development, HTTP APIs play a crucial role. They enable different software systems to collaborate and share data efficiently, much like children of different backgrounds and nationalities playing together in a playground.

Creating Your First Minimal API Application

Like straightforward characters in martial arts novels, minimal APIs attract developers with their direct and efficient approach. Let's guide you through creating your first minimal API application.

Launch Visual Studio 2022 and select "Create a new project".

In the "Create a new project" dialog:

• Type "empty" in the search template box.
• Select the "ASP.NET Core Empty" template, then click "Next".

In the "Configure your new project" dialog:

• Enter a project name such as "BookQuerySystem" (you can choose your own name).
• Select a location of your choice.
• Click "Next".

In the "Additional Information" dialog:

• Select ".NET 8.0 (Long Term Support)" as the framework.
• Check the "Configure for HTTPS" option.
• Click "Create".

After a few seconds, Visual Studio 2022 creates a project called "BookQuerySystem" using the default project template. This is a simple project. Next, press Ctrl+F5 to run the application in non-debug mode. In this mode, you can still modify code, save files, and refresh the browser to see the effects of your changes.

If the project is not configured to use SSL, Visual Studio will display a dialog:

SSL serves as a guardian for secure information transmission, responsible for encrypting data to protect its security.

• If you trust the IIS Express SSL certificate, select "Yes".
• If you agree to trust the development certificate, select "Yes".

Don't worry if you don't understand the above details at this point. Simply select "Yes". If the project is already configured to use SSL, no dialog will appear.

You can also start the application in debug or non-debug mode from the "Debug" menu.

The following image shows the application running in Microsoft Edge:

You will see the application's default response: "Hello World!", but rest assured, this indicates that the BookQuerySystem project has started successfully.

Code in the Program.cs file:

// First, we create a web application builder
// WebApplicationBuilder initializes the application and configures dependency injection, logging, etc.
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Then, we build the application instance using the builder
// The WebApplication instance is used to configure routes, middleware, and ultimately run the application
WebApplication app = builder.Build();

// Set up a route that returns "Hello World!" when accessing the root URL
// The MapGet method defines a GET route and specifies its handler function
app.MapGet("/", () => "Hello World!");

// Finally, start the application
// The app.Run() method starts the Kestrel server, which begins listening for and processing HTTP requests
app.Run();

Deep Dive into Minimal APIs

In the ASP.NET Core architecture, "minimal APIs" represent an innovative feature that has gained acclaim since its introduction in version 6.0 for its simplicity and efficiency. It employs a functional programming approach, setting up routes, handling requests, and configuring middleware through a series of commands, thereby avoiding the complexity of traditional controllers and action methods.

Why Were Minimal APIs Introduced?

Microsoft introduced minimal APIs to streamline the web application development process and enhance productivity. By reducing boilerplate code, it results in cleaner, more concise code, thereby accelerating development.

Advantages of Minimal APIs:

• Simplified Code: No need for controllers and action methods, significantly reducing code volume.
• Reduced Dependencies: Only requires built-in ASP.NET Core packages, no additional NuGet packages needed.
• Intuitive Route Configuration: Chain-style method calls for setting routes, making them easy to understand and get started with.
• Lightweight Applications
: Less code and dependencies mean faster application startup and lower memory consumption.

// Set up a route that returns a list of books when accessing /books
app.MapGet("/books", async () =>
{
    // Assume there's a book list, here we simulate with hardcoded data
    var bookCollection = new List<string> { "Modern Web Development", "Advanced C# Programming" };
    return Results.Ok(bookCollection); // Use Results.Ok to return a 200 OK response with the book list
});