Defining HTTP Endpoints in ASP.NET Core

Welcome to the course "Creating a REST API with Minimal APIs"! This is the second course in our course path on building minimal API applications with ASP.NET Core. In the first course, you learned the basics of ASP.NET Core, got familiar with its project structure, understood the concept of middleware, learned how to handle exceptions, and created your first minimal API application with a single GET endpoint. In this course, we will dive deeper into defining and handling API endpoints. By the end of this course, you will have a functional minimal API application that allows you to manage your To Do list: adding, retrieving, updating, and deleting tasks. This lesson specifically focuses on defining endpoints for various operations on ToDo items. Let's dive in!

Representational State Transfer (REST) is a simple yet powerful way to design communication between computers over the internet. Think of it as a set of rules that helps computers talk to each other clearly, using the web. REST uses HTTP, the same protocol that your web browser uses to look at websites.

In REST, resources like your to-do list items are identified by URLs. For instance:

• A URL like http://example.com/todo/1 might represent the first item on your to-do list.
• Another URL like http://example.com/todo/2 could represent the second item.

The URL points to a specific resource, while the method (or HTTP verb) specifies the operation to be performed on that resource.

To interact with a web API and perform operations on resources identified by URLs, you use HTTP verbs. These verbs define the type of operation you are performing. The most common HTTP verbs and their corresponding ASP.NET Core methods are shown in the table below:

Although PATCH is included for completeness in this lesson, we will not be practicing it in this course since it is less frequently used compared to the other methods.

In ASP.NET Core Minimal APIs, you can extract values from the URL using routing. For example, to retrieve a specific Todo item by its ID, you can define a route like /todo/{id}. Here’s how you can extract the id from the URL:

app.MapGet("/todo/{id}", (string id) => 
{
    // Logic to handle the GET request using the extracted id
});

In this example, {id} is a placeholder in the URL that will be replaced with the actual ID when the request is made. Below are some examples of URLs that would match this endpoint:

• /todo/1 where id will be 1
• /todo/abc-123 where id will be abc-123
• /todo/42 where id will be 42

To manage different operations on ToDo items, you need to define handlers for each HTTP verb. The following example shows how to set up the Program.cs file with route handlers:

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

TodoHandlers handlers = new();

app.MapGet("/todo", handlers.GetAllTodos);
app.MapGet("/todo/{id}", handlers.GetTodo);
app.MapPost("/todo", (TodoItem todo) => handlers.AddTodo(todo));
app.MapPut("/todo/{id}", handlers.ReplaceTodo);
app.MapDelete("/todo/{id}", handlers.DeleteTodo);

app.Run();

Here, we first create a WebApplication instance using the builder pattern. Then, we create an instance of the TodoHandlers class. We define the routes using app.MapGet, app.MapPost, app.MapPut, and app.MapDelete, each mapped to the corresponding handler method. The application listens to HTTP requests and routes them to the appropriate handler based on the route and HTTP verb. Finally, we call app.Run() to start the application.

The handlers are defined in the TodoHandlers class as follows:

public class TodoHandlers
{
    public IEnumerable<TodoItem> GetAllTodos()
    {
        return TodoItem.All.Values;
    }

    public TodoItem GetTodo(string id)
    {
        return TodoItem.All[id];
    }

    public void ReplaceTodo(string id, TodoItem todo)
    {
        TodoItem.All[id] = todo;
    }

    public void DeleteTodo(string id)
    {
        TodoItem.All.Remove(id);
    }

    public void AddTodo(TodoItem todo)
    {
        var id = Guid.NewGuid().ToString();
        var newTodo = new TodoItem(id, todo.Description, todo.IsCompleted);
        TodoItem.All.Add(id, newTodo);
    }
}

Let’s break down the handlers defined in the TodoHandlers class:

• Get All Todos: This handler retrieves all Todo items.
• Get Todo by ID: This handler retrieves a specific Todo item by its ID.
• Add Todo: This method adds a new Todo item to the collection. We generate a unique identifier for each new Todo item using the Guid.NewGuid().ToString() method. A Guid (Globally Unique Identifier) is a 128-bit value used to uniquely identify information. In ASP.NET Core, Guid.NewGuid() ensures a unique ID for new resources, avoiding duplicate identifiers. For example, a generated ID might look like 3f1e4d29-2f10-4bdc-9a1c-6a6cbd1a20d9.
• Replace Todo: This handler updates an existing Todo item based on its ID.
• Delete Todo: This handler deletes a ToDo item by its ID.

In this lesson, we covered an overview of common HTTP verbs and their corresponding ASP.NET Core methods, how to extract values from URLs using routing, and how to define route handlers for different HTTP verbs. You are now equipped to define and handle API endpoints using ASP.NET Core Minimal APIs. Great job!