Visão geral das APIs

ASP.NET Core fornece duas abordagens para a criação de APIs HTTP: APIs mínimas e APIs baseadas em controlador. Para novos projetos, recomendamos o uso de APIs mínimas , pois elas fornecem uma abordagem simplificada e de alto desempenho para criar APIs com código e configuração mínimos.

APIs mínimas - Recomendado para novos projetos

APIs mínimas são a abordagem recomendada para criar APIs HTTP rápidas com o ASP.NET Core. Eles permitem que você crie endpoints totalmente funcionais REST com o mínimo de código e configuração. Ignore os andaimes tradicionais 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();

As APIs mínimas suportam a configuração e a 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 da API.

Introdução às APIs mínimas

• Tutorial: Tutorial: Criar uma API mínima com 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 Referência rápida de APIs mínimas

APIs baseadas em controlador - Abordagem alternativa

ASP.NET Core também oferece suporte a uma abordagem baseada em controlador, na qual os controladores são classes derivadas do ControllerBase. Essa abordagem segue padrões tradicionais orientados a objetos e pode ser preferida para:

• Grandes aplicativos 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 baseada 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; }
}

Escolher entre abordagens

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

• Sintaxe mais simples - Menos código clichê
• Melhor desempenho - Sobrecarga reduzida em comparação com os controladores
• Testes mais fáceis - Testes unitários e de integração simplificados
• Abordagem moderna - Aproveita os recursos mais recentes do .NET

Considere APIs baseadas em controlador se precisar:

• Extensibilidade de vinculação de modelo (IModelBinderProvider, IModelBinder)
• Recursos avançados de validação (IModelValidator)
• Peças de aplicação ou o modelo de aplicação
• Suporte JsonPatch
• Suporte OData

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

Ver também

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