Общие сведения об API

2025-08-28

Примечание.

Это не последняя версия этой статьи. В текущей версии см. статью .NET 9.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущей версии см. статью .NET 9.

Внимание

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущей версии см. статью .NET 9.

ASP.NET Core предоставляет два подхода к созданию API HTTP: минимальные API и API на основе контроллера. Для новых проектов рекомендуется использовать минимальные API , так как они предоставляют упрощенный, высокопроизводительный подход для создания API с минимальным кодом и конфигурацией.

Минимальные API— рекомендуется для новых проектов

Минимальные API — это рекомендуемый подход к созданию быстрых API-интерфейсов HTTP с помощью ASP.NET Core. Они позволяют создавать полностью функционируют REST конечные точки с минимальным кодом и конфигурацией. Пропустить традиционные шаблонные шаблоны и избежать ненужных контроллеров путем свободного объявления маршрутов и действий API.

Ниже приведен простой пример, который создает API в корне веб-приложения:

var app = WebApplication.Create(args);

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

app.Run();

Большинство API принимают параметры в рамках маршрута:

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

Минимальные API поддерживают конфигурацию и настройку, необходимую для масштабирования до нескольких API, обработки сложных маршрутов, применения правил авторизации и управления содержимым ответов API.

Начало работы с минимальными API

Руководство. Созданиеминимального API с помощью ASP.NET Core
Краткий справочник. Краткий справочник по минимальным API
Примеры. Полный список распространенных сценариев с примерами кода см. в кратком справочнике по минимальным API

API на основе контроллера — альтернативный подход

ASP.NET Core также поддерживает подход на основе контроллеров, где контроллеры являются классами, производными от ControllerBase. Этот подход следует традиционным объектно-ориентированным шаблонам и может быть предпочтительнее:

Крупные приложения с сложной бизнес-логикой
Команды, знакомые с шаблоном MVC
Приложения, требующие определенных возможностей MVC

Ниже приведен пример кода для API на основе контроллеров:


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

Следующий код предоставляет те же функции, что и рекомендуемый подход к минимальному API:


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

Оба проекта API относятся к следующему классу:

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

Выбор между подходами

Начните с минимальных API для новых проектов. Они предлагают:

Более простой синтаксис — менее стандартный код
Улучшенная производительность — снижение затрат по сравнению с контроллерами
Упрощенное тестирование — упрощенное модульное тестирование и тестирование интеграции
Современный подход . Использование последних функций .NET

При необходимости рассмотрите api на основе контроллера :

Расширяемость привязки модели (IModelBinderProvider, IModelBinder)
Расширенные функции проверки (IModelValidator)
Части приложения или модель приложения
Поддержка JsonPatch
Поддержка OData

Большинство этих функций можно реализовать в минимальных API с пользовательскими решениями, но контроллеры предоставляют их вне поля.

См. также

Руководство по созданию минимального API с помощью ASP.NET Core — учебник по минимальному api
Краткий справочник по минимальным API— краткий справочник по минимальным API
Создание веб-API с помощью ASP.NET Core — общие сведения об API на основе контроллера
Руководство по созданию веб-API на основе контроллера с помощью ASP.NET Core — учебник по API на основе контроллера

Минимальные API— рекомендуется для новых проектов

Ниже приведен простой пример:

var app = WebApplication.Create(args);

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

app.Run();

Начало работы с минимальными API

Руководство. Созданиеминимального API с помощью ASP.NET Core
Краткий справочник. Краткий справочник по минимальным API

API на основе контроллера — альтернативный подход

Контроллеры — это классы, производные от ControllerBase. Этот подход следует традиционным объектно-ориентированным шаблонам.

Ниже приведен пример кода для API на основе контроллеров:


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

Следующий код предоставляет те же функции, что и рекомендуемый подход к минимальному API:


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

Оба проекта API относятся к следующему классу:

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

Выбор между подходами

Начните с минимальных API для новых проектов. При необходимости рассмотрите api на основе контроллера:

Расширяемость привязки модели (IModelBinderProvider, IModelBinder)
Поддержка привязки форм, включая IFormFile
Расширенные функции проверки (IModelValidator)
Части приложения или модель приложения
Поддержка JsonPatch
Поддержка OData

См. также

Руководство по созданию минимального API с помощью ASP.NET Core — учебник по минимальному api
Краткий справочник по минимальным API— краткий справочник по минимальным API
Создание веб-API с помощью ASP.NET Core — общие сведения об API на основе контроллера
Руководство по созданию веб-API на основе контроллера с помощью ASP.NET Core — учебник по API на основе контроллера

Поделиться через

Общие сведения об API

Минимальные API— рекомендуется для новых проектов

Начало работы с минимальными API

API на основе контроллера — альтернативный подход

Выбор между подходами

См. также

Минимальные API— рекомендуется для новых проектов

Начало работы с минимальными API

API на основе контроллера — альтернативный подход

Выбор между подходами

См. также

Обратная связь

Дополнительные ресурсы