Introducción a las API

ASP.NET Core proporciona dos enfoques para crear API HTTP: API mínimas y API basadas en controladores. En el caso de los nuevos proyectos, se recomienda usar las API mínimas , ya que proporcionan un enfoque simplificado y de alto rendimiento para compilar API con código y configuración mínimos.

API mínimas: recomendado para nuevos proyectos

Las API mínimas son el enfoque recomendado para crear API HTTP rápidas con ASP.NET Core. Permiten crear puntos de conexión totalmente funcionales REST con código y configuración mínimos. Omita el scaffolding tradicional y evite controladores innecesarios mediante la declaración fluida de las rutas y acciones de api.

Este es un ejemplo sencillo que crea una API en la raíz de la aplicación web:

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

La mayoría de las API aceptan parámetros como parte de la ruta:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/users/{userId}/books/{bookId}", 
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

Las API mínimas admiten la configuración y la personalización necesarias para escalar a varias API, controlar rutas complejas, aplicar reglas de autorización y controlar el contenido de las respuestas de API.

Introducción a las API mínimas

• Tutorial: Tutorial: Creación de una API mínima con ASP.NET Core
• Referencia rápida: Referencia rápida de LAS API mínimas
• Ejemplos: Para obtener una lista completa de escenarios comunes con ejemplos de código, consulte Referencia rápida de LAS API mínimas.

API basadas en controlador: enfoque alternativo

ASP.NET Core también admite un enfoque basado en controladores en el que los controladores son clases que derivan de ControllerBase. Este enfoque sigue los patrones tradicionales orientados a objetos y puede ser preferible para:

• Aplicaciones grandes con lógica de negocios compleja
• Teams familiarizados con el patrón MVC
• Aplicaciones que requieren características específicas de MVC

Este es el código de ejemplo de una API basada en controladores:

namespace APIWithControllers;

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

        builder.Services.AddControllers();
        var app = builder.Build();

        app.UseHttpsRedirection();

        app.MapControllers();

        app.Run();
    }
}

using Microsoft.AspNetCore.Mvc;

namespace APIWithControllers.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

El código siguiente proporciona la misma funcionalidad mediante el enfoque recomendado de LA API mínima:

namespace MinimalAPI;

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

        var app = builder.Build();

        app.UseHttpsRedirection();

        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        app.MapGet("/weatherforecast", (HttpContext httpContext) =>
        {
            var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                {
                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    TemperatureC = Random.Shared.Next(-20, 55),
                    Summary = summaries[Random.Shared.Next(summaries.Length)]
                })
                .ToArray();
            return forecast;
        });

        app.Run();
    }
}

Ambos proyectos de API hacen referencia a la siguiente clase:

namespace APIWithControllers;

public class WeatherForecast
{
    public DateOnly Date { get; set; }

    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    public string? Summary { get; set; }
}

Elección entre enfoques

Comience con las API mínimas para los nuevos proyectos. Ofrecen:

• Sintaxis más sencilla : código menos reutilizable
• Mejor rendimiento : sobrecarga reducida en comparación con los controladores
• Pruebas más sencillas : pruebas unitarias y de integración simplificadas
• Enfoque moderno : aprovecha las características más recientes de .NET.

Considere la posibilidad de usar las API basadas en controlador si necesita:

• Extensibilidad del enlace de modelos (IModelBinderProvider, IModelBinder)
• Características de validación avanzadas (IModelValidator)
• Elementos de aplicación o el modelo de aplicación
• Compatibilidad con JsonPatch
• Compatibilidad con OData

La mayoría de estas características se pueden implementar en las API mínimas con soluciones personalizadas, pero los controladores los proporcionan de fábrica.

Consulte también

• Tutorial: Creación de una API mínima con ASP.NET Core : tutorial de API mínima
• Referencia rápida de API mínimas : referencia rápida de LAS API mínimas
• Creación de API web con ASP.NET Core : introducción a las API basadas en controlador
• Tutorial: Creación de una API web basada en controlador con ASP.NET Tutorial de API basada en controlador