asp.net-web-api
Переговоры по содержимому веб-API ASP.NET

Общая информация о содержании веб-API ASP.NET

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

Есть три момента, от которых зависит интернет,

• Ресурс
• Указатель на ресурс (URL)
• Представление ресурсов

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

1. Формат XML (расширяемый язык разметки)
2. Формат JSON (JavaScript Object Notation)

Одним из стандартов службы RESTful является то, что клиент должен иметь возможность решать, в каком формате они хотят получить ответ в JSON или XML. Запрос, отправленный на сервер, включает заголовок Accept. Используя заголовок Accept, клиент может указать формат ответа.

Например,

Accept: application/xml возвращает результат в формате XML

Accept: application/json возвращает результат в формате JSON

В зависимости от значения заголовка Accept в запросе сервер отправляет ответ. Это называется Согласование контента.

Что происходит за сценой, когда мы запрашиваем данные в определенном формате?

Контроллер веб-API ASP.NET генерирует данные, которые мы хотим отправить клиенту, и передает данные в конвейер веб-API, которые затем ищут заголовок Accept для клиента. Затем выберите подходящий форматтер для форматирования данных.

Поскольку ASP.NET Web API значительно расширяем, мы также можем указать несколько значений для заголовка accept в заголовке запроса.

Accept: application/xml,application/json

В приведенном выше случае сервер выбирает первый форматтер для форматирования данных ответа.

Мы также можем указать коэффициент качества в заголовке accept. В этом случае сервер выбирает формат, который имеет более высокий коэффициент качества.

Accept: application/json;q=0.8,application/xml;q=0.5

Если мы не укажем заголовок Accept, то по умолчанию сервер выбирает форматировщик JSON.

Когда ответ отправляется клиенту в запрошенном формате, обратите внимание, что заголовок Content-Type ответа установлен в соответствующее значение. Например, если клиент запросил application/xml , сервер отправляет данные в формате XML, а также устанавливает Content-Type=application/xml .

Форматировщики используются сервером для сообщений запроса и ответа. Когда клиент отправляет запрос на сервер, мы устанавливаем заголовок Content-Type в соответствующее значение, чтобы сервер знал формат данных, которые мы отправляем.

Например, если клиент отправляет данные JSON, заголовок Content-Type устанавливается в application/json . Сервер знает, что он имеет дело с данными JSON, поэтому он использует форматирование JSON для преобразования данных JSON в .NET Type. Аналогично, когда ответ отправляется с сервера клиенту, в зависимости от значения заголовка Accept, соответствующий форматтер используется для преобразования .NET-типа в JSON, XML и т. Д.

Пример различных типов формата ответа:

Применение / JSON:

{
  "Email": "sample string 1",
  "HasRegistered": true,
  "LoginProvider": "sample string 3"
}

Приложение / XML:

<UserInfoViewModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/WebApiDemo.Models">
  <Email>sample string 1</Email>
  <HasRegistered>true</HasRegistered>
  <LoginProvider>sample string 3</LoginProvider>
</UserInfoViewModel>

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

Консолидация контента в веб-интерфейсе

Понимание концепции

Чтобы понять согласование контента в Web API, важно понимать термин « Resource .

В Интернете любая информация, которую мы можем получить, может упоминаться как HTTP resource . Существует огромное количество материала для просмотра в Интернете с различным типом контента, например, html-документами, изображениями, видео, аудио, исполняемыми файлами, электронными таблицами и т. Д. Мы можем получить любой ресурс, выполнив http-запрос ресурса uri. Ответ HTTP для запроса возвращает ресурс, а также указывает тип контента, который also known as media type .

Чтобы получить доступ к любому ресурсу, клиент может сделать HTTP-запрос, предоставив определенный uri ресурсов и http-глаголы http. Однако в дополнение к этому клиент также может указать тип accept, который является форматом контента, который пользователь ищет. «Accept-type» может быть определен в заголовках HTTP-запросов как заголовок “accept” .

Затем сервер проверяет заголовок «accept» из запросов и возвращает ответ в указанном формате, если он доступен. Обратите внимание, что сервер может возвращать ответ только в запрошенном представлении, если он доступен . Если запрошенное представление недоступно, оно возвращает ресурс в представлении по умолчанию. Именно по этой причине он называется согласованием контента.

Практический пример

В качестве примера предположим, что вы делаете запрос на http://example.com/customer/1, чтобы получить информацию о клиенте с идентификатором 1. Если вы не укажете заголовок «accept» в запросе, сервер вернет представление этого ресурса по умолчанию.

Предположим, что сервер может возвращать информацию о клиенте в json and xml both . Теперь на клиенте указывается требуемый формат информации о клиенте в заголовке «accept» в запросе. Значение заголовка “accept” может быть “application/json” для представления json или “text/xml” для представления xml. Затем сервер вернет ответ в соответствии с запрошенным форматом.

Если запрошенный формат «text / html», который не поддерживается этим хостом (как в этом примере), он simply return the resource in the default format . Ответ http содержит заголовок “content-type” который сообщает клиенту о формате ресурса.

Обратите внимание, что даже в случае, когда запрашиваемое представление ресурса недоступно, представление ресурса по умолчанию все еще возвращается.

Вот почему это называется согласованием контента .

Клиент согласовывает представление ответа, однако, если он недоступен, он получает значение по умолчанию.

Как настроить в веб-интерфейсе API

В Web API согласование содержимого может быть настроено в классе WebAPIConfig как

config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new System.Net.Http.Headers.MediaTypeHeaderValue("text/html"));

Вы также можете переопределить согласование содержимого по умолчанию в веб-API, реализовав интерфейс IContentNegotiator и его метод Negotiate, а затем настройте его в строке запроса веб-API в файле WebAPI.config, как показано ниже:

GlobalConfiguration.Configuration.Services.Replace(typeof(IContentNegotiator), new CustomContentNegotiator());

Ниже приведен пример реализации метода Negotiate.

public class CustomContentNegotiator : DefaultContentNegotiator
    {
        public override ContentNegotiationResult Negotiate(Type type, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
        {
            var result = new ContentNegotiationResult(new JsonMediaTypeFormatter(), new MediaTypeHeaderValue("application/json"));
            return result;
        }