Visão geral das APIs

ASP.NET Core fornece duas abordagens para criar APIs HTTP: APIs mínimas e APIs baseadas em controlador. Para novos projetos, é recomendável usar APIs mínimas, pois elas fornecem uma abordagem simplificada e de alto desempenho para criar APIs com o mínimo de código e configuração.

APIs mínimas – recomendado para novos projetos

APIs mínimas são a abordagem recomendada para criar APIs HTTP rápidas com ASP.NET Core. Eles permitem que você crie pontos de extremidade totalmente funcionando REST com o mínimo de código e configuração. Ignore o scaffolding tradicional e evite controladores desnecessários declarando fluentemente rotas e ações de API.

Aqui está um exemplo simples que cria uma API na raiz do aplicativo Web:

var app = WebApplication.Create(args);

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

app.Run();

A maioria das APIs aceita parâmetros como parte da rota:

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();

ApIs mínimas dão suporte à configuração e personalização necessárias para dimensionar para várias APIs, lidar com rotas complexas, aplicar regras de autorização e controlar o conteúdo das respostas à API.

Introdução às APIs Mínimas

• Tutorial: Tutorial: Criar uma API mínima com o ASP.NET Core
• Referência rápida: referência rápida de APIs mínimas
• Exemplos: Para obter uma lista completa de cenários comuns com exemplos de código, consulte a referência rápida de APIs mínimas

APIs baseadas em controlador - Abordagem alternativa

ASP.NET Core também dá suporte a uma abordagem baseada em controlador em que os controladores são classes que derivam de ControllerBase. Essa abordagem segue padrões tradicionais orientados a objetos e pode ser preferencial para:

• Aplicativos grandes com lógica de negócios complexa
• Equipes familiarizadas com o padrão MVC
• Aplicativos que exigem recursos específicos do MVC

Aqui está o código de exemplo para uma API com base em 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();
    }
}

O código a seguir fornece a mesma funcionalidade usando a abordagem de API mínima recomendada:

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 os projetos de API referem-se à seguinte classe:

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; }
}

Escolhendo entre abordagens

Comece com APIs mínimas para novos projetos. Eles oferecem:

• Sintaxe mais simples – menos código clichê
• Melhor desempenho – Sobrecarga reduzida em relação aos controladores
• Teste mais fácil – teste simplificado de unidade e integração
• Abordagem moderna – aproveita os recursos mais recentes do .NET

Considere AS APIs baseadas em controlador se você precisar:

• Extensibilidade de associação de modelo (IModelBinderProvider, IModelBinder)
• Recursos avançados de validação (IModelValidator)
• Partes do aplicativo ou o modelo de aplicativo
• Suporte a JsonPatch
• Suporte ao OData

A maioria desses recursos pode ser implementada em APIs mínimas com soluções personalizadas, mas os controladores os fornecem prontos para uso.

Confira também

• Tutorial: Criar uma API mínima com o ASP.NET Core – tutorial mínimo da API
• Referência rápida de APIs mínimas – referência rápida de APIs mínimas
• Criar APIs Web com ASP.NET Core – Visão geral das APIs baseadas em controlador
• Tutorial: Criar uma API Web baseada em controlador com o ASP.NET Core – tutorial da API baseada em controlador