Язык программирования C#9 и платформа .NET5 - Эндрю Троелсен

class="p1">Продукт ASP.NETWeb API с самого начала разрабатывался как основанная на службах инфраструктура для построения служб REST (REpresentational State Transfer — передача состояния представления), которая базируется на инфраструктуре MVC минус "V" (представление) с рядом оптимизаций, направленных на создание автономных служб. Такие службы могут вызываться с применением любой технологии, а не только тех, которые производит Microsoft. Обращения к службе Web API основаны на базовых HTTP-методах (GET, PUT, POST, DELETE) осуществляются через универсальный идентификатор ресурса (uniform resource identifier — URI), например:

http://www.skimedic.com:5001/api/cars

Он похож на унифицированный указатель ресурса (uniform resource locator — URL), поскольку таковым и является! Указатель URL — это просто идентификатор URI, который указывает на физический ресурс в сети.

При вызове служб Web API используется схема HTTP (Hypertext Transfer Protocol — протокол передачи гипертекста) на конкретном хосте (в приведенном выше примере www.skimedic.com) и специфическом порте (5001), за которыми указывается путь (api/cars), а также необязательные запрос и фрагмент (в примере отсутствуют). Обращение к службе Web API может также содержать текст в теле сообщения, как вы увидите далее в этой главе. Из предыдущей главы вы узнали, что ASP.NET Core объединяет Web API и MVC в одну инфраструктуру.

Создание действий контроллера с использованием служб REST

Вспомните, что действия возвращают тип IActionResult (или Task<IActionResult> для асинхронных операций). Кроме вспомогательных методов в ControllerBase, возвращающих специфические коды состояния HTTP методы действий способны возвращать содержимое как ответы в формате JSON (JavaScript Object Notation — запись объектов JavaScript).

На заметку! Строго говоря, методы действий могут возвращать широкий диапазон форматов. Формат JSON рассматривается в книге из-за своей популярности.

Результаты ответов в формате JSON

Большинство служб REST получают и отправляют данные клиентам с применением формата JSON. Ниже приведен простой пример данных JSON, состоящих из двух значений:

[

  "value1",

  "value2"

]

На заметку! Сериализация JSON с использованием System.Text.Json подробно обсуждалась в главе 20.

Службы API также применяют коды состояния HTTP для сообщения об успехе или неудаче. Некоторые вспомогательные методы для возвращения кодов состояния HTTP, доступные в классе ControllerBase, были перечислены в табл. 29.3. Успешные запросы возвращают коды состояния в диапазоне до 200, причем 200 (ОК) является самым распространенным кодом успеха. В действительности он настолько распространен, что вам не придется возвращать его явно. Если никаких исключений не возникало, а код состояния не был указан, тогда клиенту будет возвращен код 200 вместе с любыми данными.

Чтобы подготовиться к последующим примерам, создайте в проекте AutoLot.Api новый контроллер, добавив в каталог Controllers новый файл по имени ValuesController.cs с показанным ниже кодом:

using System.Collections.Generic;

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]

[ApiController]

public class ValuesController : ControllerBase

{

}

На заметку! В среде Visual Studio для контроллеров предусмотрены шаблоны. Чтобы получить к ним доступ, щелкните правой кнопкой мыши на имени каталога Controllers в проекте AutoLot.Api, выберите в контекстном меню пункт Add►Controller (Добавить►Контроллер) и укажите шаблон MVC Controller — Empty (Контроллер MVC — Пустой).

В коде устанавливается маршрут для контроллера с использованием значения (api) и маркера ([controller]). Такой шаблон маршрута будет соответствовать URL наподобие www.skimedic.com/api/values. Атрибут ApiController выбирает несколько специфичных для API средств (раскрываются в следующем разделе). Наконец, класс контроллера наследуется от ControllerBase. Как обсуждалось в главе 29, в инфраструктуре ASP.NET Core все типы контроллеров, доступные в классической версии ASP.NET, были объединены в один класс по имени Controller с базовым классом ControllerBase. Класс Controller обеспечивает функциональность, специфичную для представлений ("V" в MVC), тогда как ControllerBase предлагает оставшуюся базовую функциональность для приложений в стиле MVC.

Существует несколько способов возвращения содержимого в формате JSON из метода действия. Все приведенные далее примеры возвращают те же самые данные JSON с кодом состояния 200. Различия практически полностью стилистические. Добавьте в свой класс ValuesController следующий код:

[HttpGet]

public IActionResult Get()

{

  return Ok(new string[] { "value1", "value2" });

}

[HttpGet("one")]

public IEnumerable<string> Get1()

{

  return new string[] { "value1", "value2" };

}

[HttpGet("two")]

public ActionResult<IEnumerable<string>> Get2()

{

  return new string[] { "value1", "value2" };

}

[HttpGet("three")]

public string[] Get3()

{

  return new string[] { "value1", "value2" };

}

[HttpGet("four")]

public IActionResult Get4()

{

    return new JsonResult(new string[] { "value1", "value2" });

}

Чтобы протестировать код, запустите приложение AutoLot.Api; вы увидите список всех методов из ValuesController в пользовательском интерфейсе (рис. 30.1).

Вспомните, что при определении маршрутов суффикс Controller отбрасывается из имен маршрутов, поэтому конечные точки в ValuesController сопоставляются с Values, а не с ValuesController.

Для выполнения одного из методов щелкните на кнопке GET, на кнопке Try it out (Опробовать) и на кнопке Execute (Выполнить). После выполнения метода пользовательский интерфейс обновится, чтобы отобразить результаты; наиболее важная часть пользовательского интерфейса Swagger показана на рис. 30.2.

Вы увидите, что выполнение каждого метода приводит к получению тех же самых результатов JSON.

Атрибут ApiController

Атрибут ApiController, появившийся в версии ASP.NET Core 2.1, в сочетании с классом ControllerBase обеспечивает правила, соглашения и линии поведения, специфичные для REST. Соглашения и линии поведения рассматриваются в последующих разделах.

Обязательность маршрутизации с помощью атрибутов

При наличии атрибута ApiController контроллер обязан использовать маршрутизацию с помощью атрибутов. Это просто принудительное применение того, что многие расценивают как установившуюся практику.

Автоматические ответы с кодом состояния 400

Если есть проблема с привязкой модели, то действие будет автоматически возвращать код состояния HTTP 400 (Bad Request), что заменяет следующий код:

if (!ModelState.IsValid)

{

  return BadRequest(ModelState);

}

Для выполнения показанной выше проверки инфраструктура ASP.NET Core использует фильтр действий ModelStatelnvalidFilter. При наличии ошибок привязки или проверки достоверности ответ HTTP 400 в своем теле содержит детальные сведения об ошибках.