На заметку! Строго говоря, методы действий могут возвращать широкий диапазон форматов. Формат 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. Соглашения и линии поведения рассматриваются в последующих разделах.
