ASP.NET Core 2.1: Улучшения WebAPI

Атрибут [ApiController]

ASP.NET Core 2.1 добавляет атрибут [ApiController], который упрощает разработку WebAPI контроллеров. Данный атрибут предназначен для класса контроллера и обеспечивает:

• Создание ответа с HTTP кодом 400 при ошибке валидирования модели
• Автоматическое добавление атрибутов для параметров действий контроллера:
• [FromBody] для комплексных типов;
• [FromRoute] где это возможно, исходя из настроек маршрутов;
• [FromQuery] в остальных случаях.

Для корректной работы [ApiController] требуется задание маршрутов с использованием атрибутов.

ActionResult<T>

Новый тип ActionResult<T> позволяет вернуть как обобщенный ответ (например с кодом 404), так и значение заданного типа. Например:

В данном примере действие может вернуть экземпляр типа User или ответ 404, если данные не найдены.

Улучшенная обработка запроса

Еще одним нововведением в ASP.NET Core 2.1 стали улучшенные сообщения об ошибках обработки данных запроса. Например, если в запросе данные в формате JSON содержали значение неправильного типа, то раньше клиент получал в ответ следующее:

{
  "id": [
    "The input was not valid."
  ]
}

Теперь текст сообщения об ошибке стал более детальным. Для рассориваемого случая он будет выглядеть так:

{
  "id": [
    "Could not convert string to integer: abc. Path 'id', line 1, position 16."
  ]
}

Вот еще один пример ответа с пояснением ошибки:

{
  "": [
    "Unexpected end when reading JSON. Path '', line 1, position 1."
  ]
}

Валидация параметров запроса

Теперь можно добавлять атрибуты валидации непосредственно в сигнатуре Действия. Например:

Поддержка Problem Details (RFC 7808)

В ASP.NET Core 2.1 появилась поддержка RFC 7808 – Problem Details for HTTP APIs – стандарта, который определяет формат возвращаемого сообщения об ошибках HTTP API. Для использования этой возможности необходимо добавить следующий код в метод ConfigureServices:

Другой вариант – вернуть результат вызова ValidationProblem() из самого действия в контроллере.

В любом случае ответ примет следующий вид:

{
  "errors": {
    "Text": [
      "The Text field is required."
    ]
  },
  "type": "https://asp.net/core",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "Please refer to the errors property for additional details.",
  "instance": "/api/values"
}

Улучшения для JSON Patch

JSON Patch определяет структуру JSON документа для поддержки операции HTTP PATCH (частичной модификации данных). Его поддержка уже существует в ASP.NET Core. В версии 2.1 добавлена возможность использовать операцию ApplyTo для проверки на наличие заданных значений перед выполнением обновления. Например:

Следующий запрос успешно выполнит обновление данных.

[
  { "op": "test", "path": "/text", "value": "Do" },
  { "op": "add", "path": "/status/1", "value": "Done!" }
]

А обработка запроса вот с другими данными закончится ошибкой, т.к. значение свойства Text у переменной value не совпадает с заданным “Do not”:

[
  { "op": "test", "path": "/text", "value": "Do not" },
  { "op": "add", "path": "/status/1", "value": "Done!" }
]